API Starter

A progressive Node.js framework for building efficient and scalable server-side applications, heavily inspired by Angular.

Table of Contents:

1. Description
2. Prerequisites
3. Deployment
4. Environment Configuration
5. Choosing a Web Framework
6. HTTP2
7. Choosing a Database
8. Testing
9. TypeDocs
10. Logs

🔎 This repo was created with Nx.

📚 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, or apt-get.

• Please make sure to have MongoDB locally by following the guide on the MongoDB website. MongoDB can be downloaded standalone via brew, choco, or apt-get.

Remark: MongoDB can be easily deployed on a cloud provider like MongoDB Atlas - comes with a free tier option to get started quickly. This will bypass the requirement to have MongoDB locally.

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-mongo-boilerplate.

• Download dependencies via npm i or yarn.

• 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).

Remark: For SQL databases, I created a boilerplate for Nest and TypeORM.

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_URL - the connnection string to the MongoDB database.

🏗 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.

🦾 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

👥 Support

PRs are appreciated, I fully rely on the passion ❤️ of the OS developers.

License

This starter API is MIT licensed.

Author