⭐ NestJS Service Template ⭐

Template for new services based on NestJS with the Best Practices and Ready for Production

👀 Motivation

When we start creating some new service based on NestJS most often we just use the Nest cli for starting a new service that already give us some convention and structure for our project. This is a good starting point however I was missing a couple of interesting things that almost all services should have to be ready to deploy to production like fully dockerized, ensuring coding conventions...

For this reason I created this custom template for new services based on this framework, with everything I would like to have to start developing a service with the best practices but with a simple file structure so later developers can change to implement their logic.

Here we are not providing any specific architecture like hexagonal architecture or others, this is like a simple template where later we can customize and create the architecture we need.

🌟 What is including this template?

1. 🐳 Fully dockerized service ready for development and production environments with the best practices for docker, trying to provide a performance and small image just with the code we really need in your environments.
2. 👷 Use SWC for compiling and running the tests of the service. As commented in the own NestJS docs, this is approximately x20 times faster than default typescript compiler that is the one that comes by default in NestJS.
3. ⚡️ Use Fastify as Web Framework. By default, NestJS is using Express because is the most widely-used framework for working with NodeJS, however, this does not imply is the one is going to give us the most performance. Also, NestJS is fully compatible with Fastify, so we are providing this integration by default. You can check here comparison between different web frameworks.
4. 🐶 Integration with husky to ensure we have good quality and conventions while we are developing like:
   • 💅 Running the linter over the files that have been changed
   • 💬 Use conventional commits to ensure our commits have a convention.
   • ✅ Run the tests automatically.
   • ⚙️ Check our project does not have type errors with Typescript.
   • 🙊 Check typos to ensure we don't have grammar mistakes.
5. 🗂️ Separate tests over production code. By default, NestJS is combining in the same folder, the src, the unit tests and the code we are developing for production. This is something I personally don't like so here I am separating this and having a dedicated folder for the unit tests.
6. 🧪 Testing with Vitest and supertest for unit and e2e tests.
7. 🏎️ Performance testing using k6.
8. 🤜🤛 Combine unit and e2e test coverage. In the services we may have both type of tests, unit and e2e tests, and usually we would like to see what is the combined test coverage, so we can see the full picture.
9. 📌 Custom path aliases, where you can define your own paths (you will be able to use imports like @/shared/logger instead of ../../../src/shared/logger).
10. 🚀 CI/CD using GitHub Actions, helping ensure a good quality of our code and providing useful insights about dependencies, security vulnerabilities and others.
11. 🐦‍🔥 Usage of ESModules instead of CommonJS, which is the standard in JavaScript.
12. 📦 Use of pnpm as package manager, which is faster and more efficient than npm or yarn.

🤩 Other templates

Are you thinking in start new projects in other frameworks or create a super fancy library? If you like this template there are others base on this you can check:

• Template for new Typescript Libraries
• Template for new Typescript Express Services
• Template for new GitHub Actions based on NodeJS

🧑‍💻 Developing

First, we will need to create our .env file, we can create a copy from the example one:

cp .env.example .env

Now, we will need to install pnpm globally, you can do it running:

npm install -g [email protected]

The project is fully dockerized 🐳, if we want to start the app in development mode, we just need to run:

docker-compose up -d my-service-dev

This development mode will work with hot-reload and expose a debug port, port 9229, so later we can connect to it from our editor.

Now, you should be able to start debugging configuring using your IDE. For example, if you are using vscode, you can create a .vscode/launch.json file with the following configuration:

{
  "version": "0.1.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to docker",
      "restart": true,
      "port": 9229,
      "remoteRoot": "/app"
    }
  ]
}

Also, if you want to run the production mode, you can run:

docker-compose up -d my-service-production

This service is providing just a health endpoint which you can call to verify the service is working as expected:

curl --request GET \
  --url http://localhost:3000/health

If you want to stop developing, you can stop the service running:

docker-compose down

⚙️ Building

node --run build

✅ Testing

The service provide different scripts for running the tests, to run all of them you can run:

node --run test

If you are interested just in the unit tests, you can run:

node --run test:unit

Or if you want e2e tests, you can execute:

node --run test:e2e

We also have performance testing with k6, if you want to run it via docker, execute:

docker-compose up k6

Or if you want to run it from your machine, execute:

brew install k6
node --run test:performance

💅 Linting

To run the linter you can execute:

node --run lint

And for trying to fix lint issues automatically, you can run:

node --run lint:fix