A full-stack Node.js application built with Angular, and Nest based off of the Realworld OAS.
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 application is template from Sals' NEST REST TYPEORM STARTER which was made to quickly prototype backend applications. Deployed 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 PostgreSQL locally by deploying a web server stack like XAMPP. The control panel can then trigger PostgreSQL to start on localhost. PostgreSQL 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-angular-realworld-app. -
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 api will be exposed on http://localhost:3333, and the default ui will be exposed on http://localhost:4200).
Deployment of the Custom UI
-
This repo comes with a custom UI built with Angular - that can be accessed via
http://localhost:4201. This is different from the default UI that comes with the Realworld OAS. -
To start the UI, start a new terminal window and run
npm run ng serve -- --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 PostgreSQL is the database of choice but TypeORM supports other database types like SQLite, MySQL/MariaDB, 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. Therefore I created another 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 -nodesRemark: 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
# test api against postman collection
$ docker exec -it nest-rest-typeorm-api npm run test:postman
# execute test
$ npm run test
# test api against postman collection
$ npm run test:postman
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:startOut of the box, the web app comes with OAS; an open api specification, that is used to describe RESTful APIs. Nest provides a dedicated module to work with it.
The configuration for OAS can be found at this location.
The client lib is generated with OpenAPI Generator to be compatible with the UI application out of the box. The reference OAS yaml file 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.