Template for new services based on Express and Typescript with the Best Practices and Ready for Production
Starting a new service in NodeJS can be a bit frustrating, there are a lot of things to consider if we want to have a really good starting point where later we can iterate.
The main objective of this template is to provide a good base configuration for our NodeJS services that we can start using and move to production as soon as possible.
- 🐳 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.
- 👷 Use SWC for compiling and running the tests of the service.
- ⚡️ Configure Express as HTTP framework.
- 🐶 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.
- 🧪 Testing with Vitest and supertest for unit and e2e tests.
- 🏎️ Performance testing using k6.
- 🤜🤛 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.
- 📌 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
). - 🚀 CI/CD using GitHub Actions, helping ensure a good quality of our code and providing useful insights about dependencies, security vulnerabilities and others.
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 NestJS Services
- Template for new GitHub Actions based on NodeJS
First, we will need to create our .env file, we can create a copy from the example one:
cp .env.example .env
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 with work with hot-reload and exposing a debug port, the 9229
, so later we can connect from our editor to it.
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 config:
{
"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
npm run build
The service provide different scripts for running the tests, to run all of them you can run:
npm run test
If you are interested just in the unit tests, you can run:
npm run test:unit
Or if you want e2e tests, you can execute:
npm 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
npm run test:performance
To run the linter you can execute:
npm run lint
And for trying to fix lint issues automatically, you can run:
npm run lint:fix