NestJS GraphQL Fastify Template

Description

Full NodeJS boilerplate of a NestJS GraphQL API using PostgreSQL as the database.

Technologies

In terms of languages this template takes a NestJS GraphQL Code First Approach, so it's fully written in TypeScript.

In terms of frameworks it uses:

• NestJS as the main NodeJS framework;
• Fastify as the HTTP and WS adapter;
• Mercurius as the GraphQL adapter for Fastify;
• MikroORM as the ORM for interacting with the database;
• Sharp for image manipulation and optimization.

Features

Configuration (adds most used index classes):

• Cache with Redis;
• GraphQL with subscriptions and GraphQL through Websockets;
• MikroORM with SQLite in development and PostgreSQL in production.

Authentication:

• JWT Authentication (local OAuth) for HTTP;
• (Experimental) External OAuth Authentication under feature flags:
  • Google;
  • Facebook;
  • Microsoft;
  • GitHub;
• Extended JWT Authentication for Websockets using hooks (might have unexpected behaviour, needs manual testing);
• Two-Factor authentication with email.

Uploader:

• Basic image only uploader with Sharp optimizations for a generic S3 Bucket.

Pagination:

• Has the generics for Edges and Paginated types;
• Relay cursor pagination function.

Module Folder Structure

In terms of folders each module is divided as follows:

^{NOTE: this is only a recommendation you can always use your own approach as long as they work with NestJS.}

C:/home/user/Home/IdeProjects/{project-folder}/src/{module-name}:.
├─── entities
│    │ {something}.entity.ts
│    ├─── gql:
│    │     {something}.type.ts
├─── interfaces
│     {something}.interface.ts
├─── enums
│     {something}.enum.ts
├─── dtos
│     {something}.dto.ts
├─── inputs
│     {something}.input.ts
├─── tests
│     {something}.spec.ts
│ {module-name}.module.ts
│ {module-name}.service.ts
│ {module-name}.resolver.ts

Entities (entities)

• Where you save all your entities;
• The entities are the classes that represent the database tables and the Graphql Object Types;
• These are normally decorated with the @Entity decorator and the @ObjectType decorator;
• File Extension: {something}.entity.ts
• Gql (gql):
  • Where you save the Generic Graphql Object Types (ex: PaginatedUsers, etc.);
  • These are normally decorated with the @ObjectType decorator;
  • File Extension: {something}.type.ts

Interfaces (interfaces)

• Where you save all the interfaces and TypeScript types;
• File Extension: {something}.interface.ts

Enums (enums)

• Where you save all general enums and Enum Type;
• File Extension: {something}.enum.ts

Dtos (dtos)

• Where you save all the DTOs (Data Transfer Objects) mainly for your Queries;
• These are normally decorated with the ArgsType decorator;
• File Extension: {something}.dto.ts

Inputs (inputs)

• Where you save all the GraphQL Input Objects mainly for your Mutations;
• These are normally decorated with the @InputType decorator;
• File Extension: {something}.input.ts

Tests (tests)

• Where you save all the unit tests for your module's services, resolvers and controllers;
• These are normally the spec files generated by the cli, but you still need to move them to this folder;
• File Extension: {something}.spec.ts

Optional Folders

• Embeddables (embeddables):
  • Where you save all your JSON Fields for your database tables;
  • These are normally decorated with the @Embeddable decorator;
  • File Extension: {something}.embeddable.ts
• Guards (guards):
  • Where you save all your NestJS Guards related to your module;
  • File Extension: {something}.guard.ts

Initial Set Up

Installation

$ yarn install

Database Migrations

# creation
$ yarn migrate:create
# update
$ yarn migrate:update

Running the app

# production mode
$ yarn start

# watch mode
$ yarn start:dev

# debug mode
$ yarn start:debug

Local setup

1. Create a repo using this template;
2. Install the dependencies:

$ yarn install

3. Create a .env file with all the fields equal to the example.
4. Run the app in development mode:

$ yarn start:dev

Unit Testing

All tests

# unit tests
$ yarn test

Individual test

# unit tests
$ yarn test service-name.service.spec.ts

E2E Testing

# e2e tests
$ yarn test:e2e

Deployment

Steps with Dokku

1. Go to DigitalOcean, Linode or Hetzner;
2. Create a server running Ubuntu LTS;
3. Install dokku;
4. Run the following commands on your server for dokku initial set-up:

$ cat ~/.ssh/authorized_keys | dokku ssh-keys:add admin
$ dokku domains:set-global your-global-domain.com

5. Create a new app and connect git:

$ dokku apps:create app-name

6. Add the Postgres plugin to dokku, create a new PG instance and link it to the app (you should consider buying a managed database if it is going to be a production app):

$ sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git postgres
$ dokku postgres:create app-name-db
$ dokku postgres:link app-name-db app-name

7. Add the Redis plugin to dokku, and create a new Redis instance and link it to the app (again you should consider buying a managed database):

$ sudo dokku plugin:install https://github.com/dokku/dokku-redis.git redis
$ dokku redis:create app-name-redis
$ dokku redis:link app-name-redis app-name

8. Add all the other configurations as in the example file:

$ dokku index:set app-name URL=https://your-domain.com ...

9. On the project folder on your local computer run the following commands:

$ git remote add dokku dokku@server-public-ip-address:app-name
$ git push dokku main:master

10. Finally set up SSL and a domain for your app:

$ sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git
$ dokku index:set --global DOKKU_LETSENCRYPT_EMAIL=your-email@your.domain.com
$ dokku domains:set app-name your-domain.com
$ dokku letsencrypt:enable app-name
$ dokku letsencrypt:cron-job --add 

Support the frameworks used in this template

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.

Mikro-ORM is a TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. If you like MikroORM, give it a star on GitHub and consider sponsoring its development!

Sharp is a high performance Node.js image processor. If you want to support them.

License

This project is dual licensed under the Mozilla Public License 2.0 and the GNU General Public License version 3. You may use, distribute, and modify files in this project under the terms of either the MPLv2 or GPLv3, at your option.