ChristopherZhong / icatalyst-nestjs-starter

ICatalyst NestJS Starter

This project was initialized with the following command to scaffold a Nest framework TypeScript starter project.

npx @nestjs/cli new --directory . <project-name>

Static code analysis is done by ESLint and code formatting is done by Prettier. These tools are used automatically to check the code using Git hooks set up by husky and lint-staged. The tools were installed using following command.

npx mrm@2 lint-staged

Three Git hooks are provided: commit-msg, pre-commit, and prepare-commit-msg. The commit-msg hook uses the commitlint tool to lint commit messages according to the conventional commits specification. The configuration of the tool is located in the .commitlintrc.yml configuration file. The pre-commit hook automatically formats files according to the configuration specified in the .lintstagedrc.yml file. The prepare-commit-msg hook automatically appends a JIRA issue number to the commit message if the branch name that contains the [A-Z]\+-\d\+ regular expression.

Usage

The following sections describe the usage of this project.

Installation

To set up and run this project locally, run the following command. The command will install all the dependencies and set up the Git hooks.

npm install

Running the app

There are some external dependencies that need to be available before starting this project locally. See the External Dependencies section for more information. To run this project locally, use one of the following commands.

# development
npm run start

# watch mode
npm run start:dev

# production mode
npm run start:prod

This project is also configured to run using Docker and Docker Compose. Docker Compose files are provided (docker-compose.yml and docker-compose.local.yml) that can be used to run this project using Docker. A convenience script (up) is provided to start this project as follows.

./scripts/up <service>

Furthermore, the Docker Compose is already configured to allow remote debugging. In addition, a Visual Studio Code launch.json is provided that can attach a debugger to the running container.

Test

To test this project, use one of the following commands. Note that the e2e (end-to-end) tests require the external dependencies to be available.

# unit tests
npm run test

# e2e tests
npm run test:e2e

# unit test coverage
npm run test:cov

Warning: If the same database is used for development and running the e2e tests, the contents of that database will be wiped. As an alternative, a test-e2e script is provided that can be used to run the e2e tests on a different database. The script automatically starts the external dependencies and configure a different database for the e2e tests.

NestJS

Since this project uses the Nest framework, the @nestjs/cli tool can be used in the development and maintenance of this project. See https://docs.nestjs.com/cli/overview for more details.

External Dependencies

The following sections describe the dependencies of this project.

Database

This project uses a PostgreSQL database. Connection to the database is through the Prisma ORM library. Prisma provides a CLI that can be used to initialize or add Prisma. Install the CLI using the following commands.

# adds the Prisma CLI as a dev dependency
npm install --save-dev prisma
# initialize/add Prisma to the project
npx prisma init

Further details on getting started with Prisma can be read at https://www.prisma.io/docs/getting-started. Further details on NestJS integration with Prisma can be read at https://docs.nestjs.com/recipes/prisma.

When Prisma is initialized, a prisma directory is created that contains the schema.prisma schema file and a directory for migrations. Based on the schema, Prisma will generate a client that can be used to interact with the database. This client can be installed using the following command.

npm install @prisma/client

Further information on how to use the Prisma client is at https://www.prisma.io/docs/reference/api-reference/prisma-client-reference.

See https://www.prisma.io/docs/reference/api-reference/prisma-schema-reference and https://www.prisma.io/docs/concepts/components/prisma-schema for further details on the specifications of the schema. And since the underlying database is PostgreSQL, specific details on how Prisma interacts with PostgresSQL is at https://www.prisma.io/docs/concepts/database-connectors/postgresql.

Schema Development Workflow

The Prisma CLI provides ways to aid in the development of models. When there is an initial model, the following command creates a migration file, syncs the database, and updates the Prisma client.

npx prisma migrate dev --name <name-of-migration>

See https://www.prisma.io/docs/guides/database/developing-with-prisma-migrate, https://www.prisma.io/docs/concepts/components/prisma-migrate, and https://www.prisma.io/docs/reference/api-reference/command-reference#prisma-migrate for further details.

Deploying migrations to production is as simple as the following command.

npx prisma migrate deploy

When developing Prisma models for PostgreSQL, further details on the type mappings is at https://www.prisma.io/docs/concepts/database-connectors/postgresql#type-mapping-between-postgresql-to-prisma-schema.

Environment Variable(s)

There are five database environment variables and one Prisma environment variable. The database environment variables are used in the docker-compose.yml file for the database service. And the Prisma environment variable is used in the Prisma schema file in the env().

# Database
DATABASE_HOST=localhost
DATABASE_NAME=nestjs
DATABASE_PASSWORD=password
DATABASE_PORT=5432
DATABASE_USER=nestjs

# Prisma
DATABASE_URL=postgresql://${DATABASE_USER}:${DATABASE_PASSWORD}@${DATABASE_HOST}:${DATABASE_PORT}/${DATABASE_NAME}?schema=public

Environment Variable(s)

The following is a combined list of environment variables and example values.

# APP
APP_NAME=app-name
APP_PORT=3000
APP_URL=http://localhost:3000

# Database
DATABASE_HOST=localhost
DATABASE_NAME=nestjs
DATABASE_PASSWORD=password
DATABASE_PORT=5432
DATABASE_USER=nestjs

# Prisma
DATABASE_URL=postgresql://${DATABASE_USER}:${DATABASE_PASSWORD}@${DATABASE_HOST}:${DATABASE_PORT}/${DATABASE_NAME}?schema=public