A microservice boilerplate for Node.js
A microservice boilerplate for Node.js
A boilerplate to help start Node.js projects quickly and effectively. Packaged with Typescript, Docker, Kubernetes, PM2, Eslint, Prettier, VSCode config, Winston, Typedoc, Nodemon, AVA, PromClient, JWT, Editorconfig, OpenAPI/Swagger, Jaeger/Open Tracing, etc.
src
folder and gets built when you start the server in dist
folder.src/config/env
folder and .env
file in the root.src/app/routes
folder. You can place as many js files as you want within.src/app/controllers
folder.src/app/utils
folder.src/app/views
folder.public
folder.yarn typescript -g
yarn install
to get all the dependencies installedyarn start-dev
docker-compose up
to get the containers installed and started.docker-compose -f docker-compose-prod.yml up
to get the containers installed and started in production environment.Pull the container from DockerHub with the command docker pull ajays97/node-microservice-boilerplate
(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 ajays97/node-microservice-boilerplate
pm2 start pm2-dev.json
to start the development clusterThe project comes with some default kubernetes deployment and service yaml configurations. To use it, do kubectl apply -f kubernetes/deployment.yaml
and kubectl apply -f kubernetes/service.yaml
once Kubernetes and Kubectl are installed onto your system and configured.
yarn build
to build the typescript code, copy relevant filesLogs can be added by using the log function from error.utils by specifying the log level, payload, SPAN if using Jaeger and a tag object with key-value pairs.
log('info', {
message: 'Log message here',
key1: value1,
key2: value2
});
Use the toggles provided in config to decide where you want to write logs. By default, console logging is enabled and file logging is disabled but this can be changed by using the config.
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 src/app/controllers/metrics.server.controllers.ts
The project comes with prettier configs and extensions built in.
You can format the project manually by running the command npm run format
and prettier will format the project for you.
You may want to install an extension for your IDE though. More details on the same is available at https://prettier.io
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
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.
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.
A .editorconfig file has been added to the project to enable consistency in development across different IDEs used by different developers. Visit http://editorconfig.org for more information. You might have to install plugins in your editor to get this to work.
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.
The development and production environments has some notable differences in their implementation. Everything is handled automatically when run with the right compose file.
nodemon
in development and directly running with node
in productionSingle Stage Build
for Docker image in development and Multi Stage Build
for Docker image in productionsrc
mounted as volume in development and no volume mount
in productionAll files copied
to container in development and only necessary files copied
to container in productiondevDependencies installed
in development but devDependencies ignored
in productionSince this project uses all the latest features of the node ecosystem, it requires Node >= v10.0.0