{"id":21156049,"url":"https://github.com/itsmunim/simple-nodejs-scaffold","last_synced_at":"2025-07-22T20:05:51.242Z","repository":{"id":42223105,"uuid":"161025470","full_name":"itsmunim/simple-nodejs-scaffold","owner":"itsmunim","description":"The simple but essential boilerplate you wanted for API development in NodeJS","archived":false,"fork":false,"pushed_at":"2022-12-30T21:03:35.000Z","size":740,"stargazers_count":53,"open_issues_count":14,"forks_count":10,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-07-08T21:43:34.412Z","etag":null,"topics":["api","api-design","architectural-practices","architecture","backend","boilerplate","boilerplate-template","bootstrap","cli","domain","domain-driven-design","expressjs","frontend","nodejs","resources","scaffold","scaffolding","server","simple"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itsmunim.png","metadata":{"files":{"readme":"ReadMe.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-12-09T09:51:18.000Z","updated_at":"2025-01-21T21:22:12.000Z","dependencies_parsed_at":"2023-01-31T16:35:17.523Z","dependency_job_id":null,"html_url":"https://github.com/itsmunim/simple-nodejs-scaffold","commit_stats":null,"previous_names":["itsmunim/simple-nodejs-scaffold","dibosh/simple-nodejs-scaffold"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/itsmunim/simple-nodejs-scaffold","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsmunim%2Fsimple-nodejs-scaffold","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsmunim%2Fsimple-nodejs-scaffold/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsmunim%2Fsimple-nodejs-scaffold/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsmunim%2Fsimple-nodejs-scaffold/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itsmunim","download_url":"https://codeload.github.com/itsmunim/simple-nodejs-scaffold/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsmunim%2Fsimple-nodejs-scaffold/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266563915,"owners_count":23948689,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-design","architectural-practices","architecture","backend","boilerplate","boilerplate-template","bootstrap","cli","domain","domain-driven-design","expressjs","frontend","nodejs","resources","scaffold","scaffolding","server","simple"],"created_at":"2024-11-20T11:35:05.107Z","updated_at":"2025-07-22T20:05:51.211Z","avatar_url":"https://github.com/itsmunim.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003e\n    🦥 Simple NodeJS Scaffold 🦥\n  \u003c/h1\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  Simple enough service scaffolding in node and express; to get you started on your project immediately- with right folder structure and architecture practices in place 🤟🏼\n\u003c/p\u003e\n\n\n\n## Table of Contents\n\n- [Features](#features)\n- [Usage](#usage)\n- [Serving Frontend](#serving-frontend)\n- [Folder Structure](#folder-structure)\n- [Adding new API Resource](#adding-new-api-resource)\n- [Others](#others)\n\n\n\n## Features\n\n- Don't worry about the boilerplate anymore, jump right into writing your API\nresources\n\n- Easily start serving your frontend; great option to create a BFF right away\n\n- Have error handling and graceful shutdown support out of the box\n\n- Structure your code in a domain driven approach- with right architectural practices in place\n\n- Has `mongo` connectivity built-in, simply define schemas and start writing stateful APIs\n\n- Dockerized\n## Usage\n\n### Without Docker\n\n- `npm install`\n\n- Create a `.env` file using the following content, feel free to change username and password as you please:\n\n    ```\n    # COMMON\n    DB_NAME=sns-db\n\n    # SERVICE\n    VERSION=1.0.0\n    SVC_HOST_PORT=8282\n\n    # MONGO_DB\n    MONGO_USERNAME=sns-user\n    MONGO_PASSWORD=sns-012345\n    MONGO_PORT=27017\n\n    # To expose it in host network as well, please specify a port below. Change it to\n    # any other ports, if the port is already in use in host.\n    MONGO_HOST_PORT=27018\n\n    # MYSQL\n    MYSQL_ROOT_USER=root\n    MYSQL_ROOT_PWORD=root12345 # you can remove this if MYSQL_ALLOW_EMPTY_PASSWORD is set in docker-compose\n    MYSQL_PORT=3306\n\n    # To expose it in host network as well, please specify a port below. Change it to\n    # any other ports, if the port is already in use in host.\n    MYSQL_HOST_PORT=3307\n    ```\n\n- Make sure if you have your local `mongo` running. Then, this will start the server in port `8282`: `npm start`\n\n- To use `mysql`, make sure you have local mysql running with the above setup in `.env` file. Then in `server/core/connectors/index.js` comment out or remove the `mysql` option from ignore list and add `mongo` instead\n\n### With Docker\n\n- Make sure you have created an `.env` file stated above with same content\n\n- This will run the service at `8282` port with `mongo` connectivity by default:\n\n    `docker-compose build \u0026\u0026 docker-compose up -d`\n\n- To check logs: `docker-compose logs`\n\n- To shutdown: `docker-compose down`\n\n- To use `mysql` instead, check the `docker-compose` file and follow the instructions given in comments. Finally, do not forget to make the changes in `server/core/connectors/index.js` as described above and run `docker-compose build` once\n\n## Serving Frontend \n\n### Without Docker\n\nIf your frontend dir has following structure\n  ``` \n  client/\n  | - index.html\n  | - resources/ \u003c-- or may be static/ or dist/\n  ```\n\nThen, this can easily be served using-\n  ```\n  CLIENT_DIR=\u003cabsolute path of your client dir\u003e npm start\n  ```\n\nIf your `index.html` file is at one place and folder with static files in another, then the following might be your option-\n  ```\n  INDEX=\u003cabsolute path of index.html\u003e STATIC_DIR=\u003cabsolute path of static folder\u003e npm start\n  ```\n### With Docker\n\nIn the `.env` file add following value to serve from a client app:\n  ```\n  CLIENT_DIR=\u003cabsolute path of your client dir\u003e\n  ```\n  \nOr, to serve index and static files separately like stated in `Without Docker` section:\n  ```\n  INDEX=\u003cabsolute path of index.html\u003e\n  STATIC_DIR=\u003cabsolute path of static folder\u003e\n  ```\n## Folder Structure\n\nAt the root of this directory, the `index.js` works as the entrypoint for this service. It hooks up with certain modules under `server` dir and makes the service up and running when you hit- `npm start`.\n\nThis is how the `server` dir is structured at this moment:\n\n``` \n.\n├── api (all the api resources are here)\n│   ├── user\n│   │   ├── test\n│   │   │   └── controller.test.js\n│   │   ├── config.js\n│   │   ├── controller.js\n│   │   ├── index.js\n│   │   └── route.js\n│   └── index.js\n├── core (all the core functionalities of the service is bundled here)\n│   ├── bootstrapper.js\n│   ├── commonErrorHandler.js\n│   ├── logger.js\n│   └── shutdownManager.js\n├── testHelpers (test specific helpers, global vars should be here)\n│   └── globals.js\n├── utils (any utils or common helpers should be here)\n│   └── error.js\n└── index.js    \n```\n## Adding new API resource\n\n### CLI\n\nUsing the new cli tool bundled in this scaffold, adding a new api resource can be as easy as doing- \n\n`npm run add-resource \u003cresource-name-in-kebabcase\u003e`\n\nExample- `npm run add-resource order-items`\n\nPlease read the comments generated with the files to better understand the architecture and patterns involved.\n\n### Manual\n\nIf you still want to do it manually, then follow the instructions below-\n\n- Create the resource folder under `server/api` (e.g. `users`)\n\n- Create `route.js`, this will have routing definitions for all the endpoints \nunder this resource (e.g. `users/`, `users/2/profile`)\n\n- Create `controller.js`; theoretically this is where you should use different services to cater your api flow\n\n- Create `service.js`; this is where you should use different db repositories to cater business logic\n\n- You should separate out your db access logic from services and put them in a separate file called `repository.js`; services will use it to get/manipulate db records\n\n- You can have a `model.js` if required; which refers to the db schema required for this resource\n\n- If same resource require multiple models, services etc. they should be grouped under a subfolder like models, services etc. \n\n    Example: for order management api resource, this can be a scenario-\n\n    ```\n    orders/\n      models/\n      - order.js\n      - order-item.js\n\n      services/\n      - checkout.js\n      - payment.js\n    ```\n\n- Now, create a `config.js` where you should have your endpoint defined, at least-\n\n    ```\n    const config = {\n      ENDPOINT: '/order-items',\n    };\n\n    module.exports = config;\n    ```\n\n- Create an index file(`index.js`) and register the `route` and `config` to expose-\n\n    ``` \n    module.exports = {\n      route: require('./route'),\n      config: require('./config'),\n    };\n    ```\n\n- Finally register your resource in api index routing at `server/api/index.js`\n\n    ``` \n    const orderItems = require('./order-items');\n\n    ...\n    router.use(orderItems.config.ENDPOINT, orderItems.route);\n\n    module.exports = router;\n    ```\n\n\n\u003e To know more, please take a look at the given sample api resource `user` or try generating a new resource by `npm run add-resource resource-name`\n\n## Others\n\n- To run tests: `npm run test`\n\n- To check for lint errors: `npm run lint`\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsmunim%2Fsimple-nodejs-scaffold","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitsmunim%2Fsimple-nodejs-scaffold","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsmunim%2Fsimple-nodejs-scaffold/lists"}