Nest API Boilerplate

English | 简体中文

This project aims to provide an API project boilerplate based on nestjs, which already includes or will soon include the following basic functions:

• Database
  • Migrations
• API
  • Authentication
    • Passport
      • Local strategy
      • LDAP strategy
      • JWT strategy
  • Authorization
    • Basic RBAC (Role-based access control)
    • Claims-based authorization (TBD)
  • Pagination and filtering
  • Health check
    • orm
    • memory
    • disk
  • Rate limiting
  • Caching
• Task Scheduling
• Testing
  • Unit testing framework
  • E2E testing framework

Development environment preparation

1. Install dependencies

$ npm install

2. Environment variable configuration

App will load .env.${APP_ENV} file in project root as environment variable file when starting up. If APP_ENV is not be set, app will load .env file in project root as environment variable file. For example, if APP_ENV=production, app will load .env.production as environment variable file.

To create an environment variable file, you can copy it from the .env.example file:

$ cp .env.example .env

You can modify the configuration as needed.

3. Initiate the development environment infrastructure

In order to quickly start working in the development environment, here are some services that the development environment needs to use, which will run in Docker containers.

• postgres
• pgweb
• integresql

Run the following command to start all the basic services mentioned above:

$ docker compose -f docker-compose-dev-infra.yml --env-file .env up

4. Initialize the development environment database

Create a development environment database:

$ npm run db:create

5. Run database migration script

Due to the fact that the development database in the newly built development environment is brand new and has no schema, it is necessary to run the accumulated migration scripts to update the database schema:

$ npm run migration:run

6. Add data seeds to the database (optional)

This step is optional. If some data seeds have already been defined in the project, running the following script can quickly synchronize some initial data to the database:

$ npm run seed:run

Data seeds are usually placed in the modules/*/testing/*.seeder.ts file.

Compile and run the project

# development
$ npm run start

# watch mode
$ npm run start:dev

# production mode
$ npm run start:prod

Run tests

1. Unit Test

Unit test files are usually placed in the same directory as functional code. In this project template, there are all files in the src directory that end with .spec.ts. Run unit tests:

$ npm run test:unit

2. E2E Test

E2E testing files are generally not placed together with functional code. In this project template, they are all files in the test directory that end with .e2e-spec.ts. Run end-to-end testing:

$ npm run test:e2e

3. All Test

Run all tests at once without distinguishing test types:

$ npm run test

E2E tests require PostgreSQL and IntegreSQL. For local development, start the development infrastructure first:

$ docker compose -f docker-compose-dev-infra.yml --env-file .env up

Production readiness

This template is JWT-first and does not mount server-side session middleware by default. Tokens are accepted from the Authorization: Bearer header only.

Before using this template in production:

• Set NODE_ENV=production.
• Use a random APP_SECRET with at least 32 characters.
• Set explicit ALLOWED_ORIGINS; wildcard CORS is not allowed by validation in production.
• Keep API_DOCS_ENABLED=false unless the deployment is private.
• Configure database pool variables:
  • DATABASE_POOL_MAX
  • DATABASE_POOL_IDLE_TIMEOUT_MS
  • DATABASE_POOL_CONNECTION_TIMEOUT_MS
• Configure database SSL with DATABASE_SSL_MODE; use verify-ca or verify-full with DATABASE_SSL_CA when your platform provides a CA bundle.
• Run migrations before serving traffic.
• Use /health/live for liveness probes and /health/ready for readiness probes.

CI

GitHub Actions are defined in .github/workflows/ci.yml. Reusable CI commands live in the ci/ directory:

$ bash ci/validate.sh
$ bash ci/test-e2e.sh

The CI workflow starts PostgreSQL and IntegreSQL services, then runs build, unit tests, and E2E tests.

Migrations

1. Generate

When you modify the code of any database entity, specifically the classes decorated with the @Entity() provided by typeorm, you can run the following script to have typeorm automatically generate a database migration script:

$ npm run migration:generate

The generated database migration script will be placed in the src/database/migrations/ directory.

2. Revert

If you want to revert the latest database migration script, you can run the following command:

$ npm run migration:revert

It should be noted that each time this command is run, only the most recent database migration script will be revoked. If you need to revoke multiple times, you need to run the script continuously for the corresponding number of times.

Data pagination

This template uses nestjs page to support data pagination.

Others

1. Using an interactive environment

REPL (Read Eval Print Loop) is an interactive environment that accepts single user inputs, executes them, and returns the results to the user. The REPL function allows you to directly check the dependency graph from the terminal and call methods on the provider (and controller):

$ npm run start:repl