A progressive Node.js framework for building efficient and scalable server-side applications, heavily inspired by Angular.
Nest framework TypeScript starter repository.
This starter project comes preconfigured with the following features:
- Docker support
- Dockerized databases postgres, mysql, and mssql (up to you)
- Debugging locally or within a container
- Typescript support
- Typeorm for database objects and schema migrations
- Configuration management
- Logging
- Swagger API documentation
And more to come...
$ npm install
The application accepts environment variables. You can pass enviroment variables directly or via .env
file. (DO NOT CHECK .env FILES INTO SOURCE CONTROL)
Environment variables are provided to the app via the ConfigService
located at app/src/common/services/config.service.ts
.
Environment variables are grouped via config providers, such as the AppConfigProvider
class. Additional providers may added as necessary. The application should try to avoid using process.env
when possible.
# development
$ npm run start
# watch mode
$ npm run start:dev
# production mode
$ npm run start:prod
To debug the application locally you can use one of two methods.
VSCode
- Click the debug panel and select
Local: Attach to Node
config and then click run.
Chrome
- run
npm run start:debug
- navigate to chrome://inspect and click
inspect
under REMOTE TARGET.
# building dev container
$ docker-compose -f ./docker-compose.dev.yml up --build
# building debug container
$ docker-compose -f ./docker-compose.debug.yml up --build
Once the debug container is running you can launch the debugger from either Chrome or VSCode.
VSCode:
Click the debug panel and select Docker: Attach to Node
config and then click run.
Chrome:
navigate to chrome://inspect and click inspect
under REMOTE TARGET.
This starter project comes pre-configured with three databases. Click on each for instructions on how to get started. Feel free to remove whichever ones your application does not need. To remove the unnecessary databases just delete their configurations from all docker-compose files.
Once you have the containers up, run the following command to choose the database you wish to connect to.
$ docker-compose -f docker-compose.dev.yml ps
Using the Name of the container output above, connect using the appropriate command listed below:
Postgresql
$ docker exec -it [NAME] psql -U admin development
MySQL
$ docker exec -it [NAME] mysql -u root -p development
MSSQL
$ docker exec -it [NAME] /opt/mssql-tools/bin/sqlcmd -S localhost -U SA -P "[SA_PASSWORD]"
This starter project supports an orm called TypeORM in the Data
module located at app/src/modules/Data
. This ORM will work with any of the above databases.
The connection to the database is controlled by db.config.ts
file located at the root of the Data
module.
This configuration also tells the cli where it can find migrations and entity classes.
This project comes with a sample entity called user
located app/src/modules/Data/entities/user.entity.ts
. There is also a sample repository class for users
.
Entities will map to a database table and are classes decorated with @Entity()
decorator.
Entities will be used by the TypeORM
cli to generate migrations.
This starter project comes configured with a npm script to generate, run, and revert migrations scripts, typeorm:data
. To learn how migrations work see here.
NOTE: Be sure the database is running before generating, running, or reverting any migration script.
NOTE: Due to the differences between database types (postgres, mysql, mssql) migrations scripts are database specific. A migration script for postgres will not work on mssql for example.
To create an empty migration use the following command:
$ npm run typeorm:data migration:create -- -n [MigrationName]
To generate a migration for new entities or entity changes
$ npm run typeorm:data migration:generate -- -n [MigrationName]
To apply the latest migrations to the database
$ npm run typeorm:data migration:run
To revert the last migration applied to the database
$ npm run typeorm:data migration:revert
NOTE: When the application runs it will automatically apply any new migrations to the database.
If your application requires multiple databases you are in luck, this project can be easily modified to support it.
Duplicate the Data
module and update the new db.config.ts
file to work with the new database env variables and entities/migrations directory.
You must also duplicate the npm typeorm:data
script (i.e. typeorm:newdb
), update it to point to the new db.config.ts
file.
This will allow you to maintain two databases keeping their migrations and entities separate. You may repeat this process for each additional database.
# unit tests
$ npm run test
# e2e tests
$ npm run test:e2e
# test coverage
$ npm run test:cov
Swagger is preconfigured in this starter project. Once you have the application running you can navigate to http://localhost:3000/swagger to view the generated documentation. For more information on how Nestjs & swagger play together see here.
To add information about your API endpoints you can add @ApiResponse()
decorator to your controller methods. This will allow you to add more information about your API's response codes.
@Post('user')
@ApiResponse({ status: 201, description: 'User record created successfully.'})
@ApiResponse({ status: 400, description: 'User not created'})
async postUser(@Body() user: UserDto) { }
To expose your DTO objects via swagger you must apply the @ApiProperty()
decorator to the properties which you wish to expose.
import { ApiProperty } from '@nestjs/swagger';
export class UserDto {
@ApiProperty()
readonly email: string;
@ApiProperty()
readonly firstName: string;
@ApiProperty()
readonly lastName: string;
@ApiProperty()
readonly middleName: string;
}
Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please read more here.