API Starter
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
📚 Description
This boilerplate is made to quickly prototype backend applications. It comes with authentication/authorization, logging, crud features and database persistence out of the box.
🛠️ Prerequisites
Non Docker
-
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
.
🐳
Docker - Please make sure to have Docker Desktop operational to quickly compose the required dependencies. Then follow the docker procedure outlined below.
🚀 Deployment
Manual Deployment without Docker
-
Clone the repo via
git clone https://github.com/msanvarov/nest-rest-typeorm-boilerplate
. -
Download dependencies via
npm i
oryarn
. -
Create a .env file via the
cp .env.example .env
command 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.
🐳
Deploying with Docker - 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).
🔒 Environment Configuration
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.
🏗 Choosing a Web Framework
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.
💾 Choosing a Database
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.
🦾 HTTP/2
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.
✅ Testing
🐳
Docker # 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
Non-Docker
# execute test
$ npm run test
💡 TypeDocs
The 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:start
📝 Open API
Out 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
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.
🔊 Logs
This boilerplate comes with a Winston module for extensive logging, the configurations for Winston can be found in the app module.
🏗️ Progress
Branches | Status |
---|---|
main | |
feat/* |
👥 Support
PRs are appreciated, I fully rely on the passion
License
This starter API is MIT licensed.