⭐ Express Typescript basic boilerplate ⭐

Very basic NodeJS using Express and Typescript template, especially focused on providing a good starting point with all the tooling neede as code quality, bundle, lint, test etc... 🚀

📗 Features

1. Typescript as main language. 🦄
2. Fully dockerized service. 🐳
3. SWC for compiling and running the tests of the service.
4. Express as framework, but you can replace it by any and build a more sophisticated layered architerture, clean etc.
5. Pre commit and pre push actions using husky:
   • pre-commit: linting.
   • pre-push: run tests.
6. Testing with Vitest and supertest for unit and e2e tests. 🧪
7. Performance testing using k6.
8. 🚀 CI/CD using GitHub Actions.

Getting Started

Installation

First, you will need to clone the repository:

git clone

Then, you will need to install the dependencies:

npm install

Running

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

cp .env.example .env

the file only includes one variable, the PORT where the service will be running, but this means that the configuration package is working and you can include more variables in the future.

PORT=3000

The config module is using the dotenv package, so you can include more variables in the future.

export const config = {
  server: {
    port: process.env.PORT || 3000,
  },
};

Run the service in development mode:

npm run dev

Container

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

⚙️ Building

npm run build

✅ Testing

The service provide unit and e2e tests, you can run them executing, they are not separated in different folders, but you can do it if you want to:

npm run test

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 # if you have a mac
npm run test:performance

winget install k6 # if you have a windows
npm run test:performance

💅 Linting

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