A progressive Node.js framework for building efficient and scalable server-side applications, heavily inspired by Angular.
Table of Contents:
- Description
- Prerequisites
- Deployment
- Environment Configuration
- Choosing a Web Framework
- HTTP2
- Choosing a Database
- Testing
- TypeDocs
- Logs
🔎 This repo was created with Nx.
This boilerplate is made to quickly prototype backend applications. It comes with authentication/authorization, logging, crud features and database persistence out of the box.
-
Please make sure to have Node.js (16+) locally by downloading the Javascript runtime via
brew,choco, orapt-get. -
Please make sure to have MYSQL locally by deploying a web server stack like XAMPP. The control panel can then trigger MYSQL to start on localhost. MYSQL can be downloaded standalone via
brew,choco, orapt-get.
- Please make sure to have Docker Desktop operational to quickly compose the required dependencies. Then follow the docker procedure outlined below.
-
Clone the repo via
git clone https://github.com/msanvarov/nest-rest-typeorm-boilerplate. -
Download dependencies via
npm ioryarn. -
Create a .env file via the
cp .env.example .envcommand and replace the existing environment variable placeholders with valid responses. -
Start the api in development mode by using
npm run start(the app will be exposed on http://localhost:3333; not to conflict with React, Angular, or Vue ports).
Optional deployment of the UI
-
This repo comes with a UI built with Angular - that can be accessed via
http://localhost:4200. -
To start the UI, start a new terminal window and run
npm run start --project ui.
Remark: In the docker deployment, the UI is automatically started and served by the API.
- Execute the following command in-app directory:
# creates and loads the docker container in detached mode with the required configuration
$ docker-compose up -d- The following command will download dependencies and execute the web application on http://localhost:80 (deployed behind a Nginx reverse proxy).
By default, the application comes with a config module that can read in every environment variable from the .env file.
APP_ENV - the application environment to execute as, either in development or production. Determines the type of logging options to utilize. Options: development or production.
WEBTOKEN_ENCRYPTION_KEY - the key to encrypt/decrypt web tokens with. Make sure to generate a random alphanumeric string for this.
WEBTOKEN_EXPIRATION_TIME - the time in seconds when the web token will expire; by default, it's 2400 seconds which is 40 mins.
DB_TYPE - the type of database connection to use.
DB_USERNAME - username for authenticating against the database.
DB_PASSWORD - password for authenticating against the database, can be left empty if a password is not needed (not safe).
DB_HOST - the endpoint where this database sits (default is localhost but can be set explicitly).
DB_PORT - default ports for different types of database connections.
DB_DATABASE - the actual database name to perform operations on.
This boilerplate comes with Fastify out of the box as it offers performance benefits over Express. But the Express adapter is still accessible on a different branch.
By default MYSQL/MariaDB are the database of choice but TypeORM supports other database types like SQLite, Postgres, MongoDB, and MSSQL. To use anything other than MYSQL/MariaDB, change the configuration in the .env file, and download the corresponding wrapper library, like SQLite3.
Check https://typeorm.io/ for supported database types.
Remark: For MongoDB, TypeORM is not as feature-rich as Mongoose. Thus, I created a boilerplate for Nest and Mongoose.
Luckily, Fastify can enable HTTP2 over either HTTPS (h2) or plaintext (h2c) out of the box. This boilerplate makes use of this on the feat/http2 branch where a self-signed certificate was created for testing this capability. The certificate is located in the certs folder. For production, please use a valid certificate.
The self signed certificate can be generated via OpenSSL:
$ openssl req -x509 -newkey rsa:4096 -keyout api-key.pem -out api-cert.pem -days 365 -nodes
Remark: Express can be ran with HTTP/2 by employing the spdy library.
# Start the docker container if it's not running
$ docker start nest-rest-typeorm-api
# unit tests
$ docker exec -it nest-rest-typeorm-api npm run test
# execute test
$ npm run testThe documentation for this boilerplate can be found on Github pages.
The docs can be generated on-demand, by typing npm run typedocs:api:start. This will produce a docs/api folder with the required front-end files and start hosting on localhost.
Remark: The docs for the ui are generated on-demand, by typing
npm run typedocs:ui:start. This will produce a docs/ui folder with the required front-end files and start hosting on localhost.
# generate docs for api code
$ npm run typedocs:api:startOut of the box, the web app comes with Swagger; an open api specification, that is used to describe RESTful APIs. Nest provides a dedicated module to work with it.
The configuration for Swagger can be found at this location.
TypeORM is an object-relational mapping that acts as an abstraction layer over operations on databases. Please view the documentation for further details.
The configuration for TypeORM can be found in the app module.
This boilerplate comes with a Winston module for extensive logging, the configurations for Winston can be found in the app module.
| Branches | Status |
|---|---|
| main | ✅ |
| feat/* | 🚧 |
PRs are appreciated, I fully rely on the passion ❤️ of the OS developers.
This starter API is MIT licensed.