A boilerplate to help start Node.js projects quickly and effectively. Packaged with Typescript, Docker, PM2, Eslint, VSCode config, Winston, Typedoc, Nodemon, AVA, PromClient, JWT, OpenAPI/Swagger, etc.
Motive behind this project
Having worked on a lot of node.js projects, I had to repetitively do the same tasks over and over again, get a project structure, install stuff, implement standardization, containerize it, implement logging, and make sure everything is in place before I start off. This takes all the burden out and lets people focus just on the logic and nothing else.
You can find the article I wrote on this project here: https://medium.com/techahoy/building-a-boilerplate-for-microservices-part-1-166ce00f5ce9
Basic Concepts behind the architecture
- All the code you write resides within
srcfolder and gets built when you start the server in
- All configuration is stored against the respective environment in
.envfile in the root.
- All your navigation routes are placed in
src/app/routesfolder. You can place as many js files as you want within.
- All your logic is written in controllers placed within
- If you have utility functions which you will use across controllers, put them in
- All the server side rendered template files are to be placed in
- All your static files and content is to be placed in the
- Install node.js and git
- Add them to path if not already in path.
- Install typescript globally with
npm install typescript -g
- Run npm install to get all the dependencies installed
- cd to the project directory and run tsc to build using typescript
npm run-script start-dev
Cloning & Running with Docker
- Install Docker and Docker Compose
- Clone/Download the repository and CD to it
docker-compose upto get the containers installed and started.
Pulling & Running from Docker Hub
Pull the container from DockerHub with the command
docker pull tvvignesh/node-skeleton(Add version if you want)
Then, start the container using the command:
docker run -d -p 8085:8085 -p 9229:9229 -e NODEJS_PORT=8085 -e NODE_ENV=development -e NODEJS_IP=0.0.0.0 tvvignesh/node-skeleton
Running via PM2
- Install node.js and pm2
- CD to the pm2 directory
pm2 start pm2-dev.jsonto start the development cluster
Building the code
npm run buildto build the typescript code, copy relevant files
Winston logging can be added by using the winston library.
logger.log('error', 'Internal server error - ' + err.stack, err);
By default, logging occurs in console in the development environment and gets written to files within logs folder in other environments.
You can place all your static files in the
public directory and that will get served by the server directly
The project is bundled with prom-client to enable exporting the metrics to prometheus with ease. You can access the default metrics at "/metrics" endpoint. You can modify what you export in
You can customize rules if needed using the .eslintrc file placed in the root directory. If you are using VSCode, you can have the ESLint extension installed. While linting is run everytime you build/start the server, you can manually run it by
npm run lint
Generate API Documentation (OpenAPI/Swagger)
You can generate documentation site by providing details regarding all the endpoints in the
apidoc.yaml file in the root and once done, you can start the server and your documentation will get exposed in
/api-docs URL. You can use tools like OpenAPI GUI to help generate the YAML file for you.
Generate Code Documentation
You can generate documentation based on your code by running
npm run document. Once generated, you can find the documentation in the docs folder. See this to know how to document your code to be rendered by the doc generator.
Helpers Utilities for doing JWT authentication is added to
src/app/utils/auth.utils.ts and controllers for the same in
src/app/controllers/auth.server.controller.ts. The private and public keys are placed in the
creds folder. You can generate your own by using tools like this.
No database implementation has been made so far and hence you may need to add your own tables/collections, create users, store secret keys, etc. which is more of an implementation detail.
You can run your tests by using
npm run test command. The project is bundled with AVA as the test framework.
You can set up the environmental variables in the .env file and that will get used in files like docker-compose, Dockerfile, etc. In addition to this, you can set up the rest of the environmental configurations in
config/env/yourenv.ts where yourenv can be anything and the respective configs will get loaded depending on env you set.
Since this project uses all the latest features of the node ecosystem, it requires Node >= v10.0.0
- Find any bugs? Please raise it as an issue.
- Have something to contribute? Please raise a pull request.
- Looking for enhancements? Please check the milestones, and if you don't find it, raise an issue.
Using this Project?
Incase you are using this project, please let me know by dropping me a mail to firstname.lastname@example.org or raising an issue, I will add you to the list of users.
Since I am doing this project purely out of interest, I am not looking for donations. But, if you want to do something, donate for charity on behalf of this project and I will add you to the contributors list.