Node.js Boilerplate

---

Table of Contents

1. About The Project
   • Context
2. Libraries and Tools
   • Dependencies
   • Dev Dependencies
3. Getting Started
   • Prerequisites
   • Optionals
   • Env Variables
   • Preparing
   • Run Tests
   • Start Server
4. In Production
   • REST API Docs
   • GraphQL Playground
5. Contact

About The Project

The Node.js Boilerplate is a project developed in TypeScript that uses concepts of Clean Architecture and Domain-Driven Design (DDD) to maintain a decoupled and domain-centered application structure.

In addition, various other design patterns are applied throughout the project to solve common software design problems encountered during the development process.

Finally, the use of Test-Driven Development (TDD) ensures several benefits for the code, such as better design, quality, greater development agility, and ease of maintenance and refactoring.

Context

The project's goal is to demonstrate how it is possible to develop software in a decoupled manner. Thus, the example used in this boilerplate is extremely simple and can be divided into two main sets of features: Authentication and Persons.

The Authentication functionality allows Sign Up in the system and ensures that the access token is generated (Sign In) so that Persons resources, which are protected, can be accessed.

The Persons functionality allows an authenticated user to Fetch Persons in a paginated way and Get Person By Id.

Interaction with the API can be done in two ways, through the REST API or the GraphQL API.

Libraries And Tools

This section describes the main libraries and tools used in the project, separated between development and production dependencies.

Dependencies

• @apollo/server - 5.2.0
• @as-integrations/fastify - 3.1.0
• @fastify/cors - 11.2.0
• @fastify/swagger - 9.6.1
• @prisma/adapter-pg - 7.2.0
• @prisma/client - 7.2.0
• @scalar/fastify-api-reference - 1.40.5
• @scalar/themes - 0.13.26
• bcryptjs - 3.0.3
• fastify - 5.6.2
• graphql - 16.12.0
• jsonwebtoken - 9.0.3
• pg - 8.16.3
• zx - 8.8.5

Dev Dependencies

• @commitlint/cli - 20.2.0
• @commitlint/config-conventional - 20.2.0
• @eslint/js - 9.39.2
• @faker-js/faker - 10.1.0
• @semantic-release/changelog - 6.0.3
• @semantic-release/commit-analyzer - 13.0.1
• @semantic-release/git - 10.0.1
• @semantic-release/github - 12.0.2
• @semantic-release/release-notes-generator - 14.1.0
• @types/bcryptjs - 3.0.0
• @types/eslint-config-prettier - 6.11.3
• @types/jsonwebtoken - 9.0.10
• @types/node - 25.0.3
• @types/pg - 8.16.0
• @types/supertest - 6.0.3
• @typescript-eslint/parser - 8.50.0
• @vitest/coverage-v8 - 4.0.16
• @vitest/ui - 4.0.16
• coveralls - 3.1.1
• dotenv - 17.2.3
• eslint - 9.39.2
• eslint-config-prettier - 10.1.8
• eslint-import-resolver-typescript - 4.4.4
• eslint-plugin-import - 2.32.0
• eslint-plugin-prettier - 5.5.4
• eslint-plugin-promise - 7.2.1
• eslint-plugin-vitest-globals - 1.5.0
• globals - 16.5.0
• husky - 9.1.7
• kleur - 4.1.5
• lint-staged - 16.2.7
• npm-check - 6.0.1
• openapi-types - 12.1.3
• prisma - 7.2.0
• semantic-release - 25.0.2
• supertest - 7.1.4
• tsup - 8.5.1
• tsx - 4.21.0
• typescript - 5.9.3
• typescript-eslint - 8.50.0
• vite-tsconfig-paths - 6.0.3
• vitest - 4.0.16
• vitest-mock-extended - 3.1.0

Getting Started

This section describes the main libraries and tools used in the project, separated between development and production dependencies.

Prerequisites

In addition to Node.js, some other tools are required to run this project:

• Node.js - 24.12.0
• Docker - 28.5.1

Optionals

You can also install this toolkit for a better experience:

• Cursor - 1.7
• Insomnia - 11.6.1

Env Variables

For security reasons, the .env file is not versioned, meaning it is not sent to the GitHub repository.

So you can copy and paste the .env.example file and rename it to .env. Then, you need to configure the environment variables.

You must also setup a .env.test to run the tests.

All variables can be configured according to your preferences.

I recommend that you leave the DATABASE_URL variable as it is in the example, as it refers to the other database configuration environment variables.

The only point of attention is regarding JWT_PRIVATE_KEY and JWT_PUBLIC_KEY. The JWT adapter reads the base64 values of these two environment variables. That is, in this case, there is no reading of the .pem files to obtain the keys.

To generate a pair of keys on MacOS, you can use these commands:

# generate private key
openssl genpkey -algorithm RSA -out private-key.pem -pkeyopt rsa_keygen_bits:2048

# generate public key
openssl rsa -pubout -in private-key.pem -out public-test-key.pem

Now it is necessary to transform the .pem files into base64. To do this on MacOS, you can follow these steps:

# transform private key in base64
openssl base64 -in private-key.pem -out private-key.txt

# transform public key in base64
openssl base64 -in public-key.pem -out public-key.txt

Now, the values obtained in the .txt files are the private and public keys in base64. These are the values that you must set for JWT_PRIVATE_KEY and JWT_PUBLIC_KEY.

Preparing

Install the dependencies with your favorite package manager (npm, yarn, or pnpm). In the example below, the default package manager for Node.js, npm, will be used:

npm install

Run Tests

To run unit tests (*.spec.ts):

npm run test

To run unit tests (*.spec.ts) in watch mode:

npm run test:watch

To run e2e tests (*.test.ts):

npm run test:e2e

To run e2e tests (*.test.ts) in watch mode:

npm run test:e2e:watch

To run all tests unit and e2e tests (*.spec.ts and *.test.ts)

npm run test:ci

Start Server

If database container is running, you can run:

npm run start:dev

Or you can use wizard:

npm run wizard

And choose option 5!

Contact