gem-hunter

NestJS boilerplate with TypeORM, GraphQL and PostgreSQL

• 1. Open for Contribution

• 2. Getting Started

  • 2.1. Installation
  • 2.2. Run

• 3. Docker

  • 3.1. Docker Compose Installation
  • 3.2. Before Getting Started
  • 3.3. Run
  • 3.4. Note
  • 3.5. Run Only Database (Local Dev)

• 4. NestJS

• 5. PostgreSQL Database

• 6. TypeORM

  • 6.1. Migration Setup and Usage

• 7. GraphQL

  • 7.1. Protected Queries/Mutation By Role
  • 7.2. GraphQL Query To Select and Relations
  • 7.3. Field-Level Permission
  • 7.4. GraphQL Status Code

• 8. Custom CRUD

• 9. Code generator

• 10. Caching

  • 10.1. How To Use

• 11. TDD

  • 11.1. Introduction
  • 11.2. Before Getting Started
  • 11.3. Unit Test (with mock)
  • 11.4. Integration Test (with in-memory DB)
  • 11.5. End To End Test (with docker)

• 12. CI

  • 12.1. Github Actions
  • 12.2. Husky v9

• 13. SWC Compiler

  • 13.1. SWC + Jest error resolution

• 14. Todo

• 15. License

Totally open for any Pull Request, please feel free to contribute in any ways. There can be errors related with type or something. It would be very helpful to me for you to fix these errors.

Before you start, make sure you have a recent version of NodeJS environment >=14.0 with NPM 6 or Yarn.

The first thing you will need is to install NestJS CLI.

$ yarn -g @nestjs/cli

And do install the dependencies

$ yarn install # or npm install

for development

$ yarn dev # or npm run dev

for production

$ yarn build # or npm run build
$ yarn start # or npm run start

or run with docker following below

Download docker from Official website

Before running Docker, you need to create an env file named .production.env. The content should be modified based on .example.env. The crucial point is that DB_HOST must be set to 'postgres'.

Open terminal and navigate to project directory and run the following command.

# Only for production
$ docker compose --env-file ./.production.env up

If you want to use docker, you have to set DB_HOST in .production.env to be postgres. The default set is postgres

You can just create PostgreSQL by below code, sync with .development.env

$ docker run -p 5432:5432 --name postgres -e POSTGRES_PASSWORD=1q2w3e4r -d postgres

Base NestJS, We like it

We use PostgreSQL for backend database, The default database that will be used is named 'postgres' You have to have PostgreSQL Database server before getting started. You can use Docker PostgreSQL to have server easily

We use Nestjs/TypeORM In this template, We've been trying not to use Pure SQL to make the most of TypeORM.

This project uses TypeORM's migration feature to manage database schema changes. Follow the steps below to generate and apply migrations.

Note

1. The custom typeorm command defined in package.json is configured for NODE_ENV=production.
2. Migrations are intended for production use, while typeorm synchronize should be used for development purposes.
3. You can see the detailed configuration code here
4. As you can see from the configuration code, migration files must be located in the subdirectory of /src/common/database/migrations/${name}.

To reflect new changes in the database, you need to first generate a migration file.

yarn migration:generate ./src/common/database/migrations/init

you can change the name of migration by replacing init

To apply the generated migration to the database, run the following command:

yarn migration:run

To roll back the last applied migration, use the following command:

yarn migration:revert

To view the current status of your migrations, run:

yarn migration:show

You can also directly create a migration file using the following typeorm command:

yarn migration:create ./src/common/database/migrations/init

This command generates an empty migration file where you can manually add your schema changes.

We use GraphQL in a Code First approach (our code will create the GraphQL Schemas).

We don't use swagger now, but you can use this if you want to. You can see playground

We use Apollo Server Playground by default. If you'd prefer the original GraphQL Playground, enable it as follows:

// src/common/config/graphql-config.service.ts

GraphQLModule.forRootAsync <
  ApolloDriverConfig >
  {
    ...
    createGqlOptions(): Promise<ApolloDriverConfig> | ApolloDriverConfig {
      ...
      playground: true,
      ...
    }
    ...
  };

Some of the GraphQL queries are protected by a NestJS Guard (GraphqlPassportAuthGuard) and requires you to be authenticated (and some also requires to have the Admin role). You can solve them with Sending JWT token in Http Header with the Authorization.

# Http Header
{
  "Authorization": "Bearer TOKEN"
}

• getMe (must be authenticated)
• All methods generated by the generator (must be authenticated and must be admin)

• Automatically maps GraphQL queries to optimized SELECT and JOIN clauses in TypeORM.

• Ensures that only the requested fields and necessary relations are retrieved, reducing over-fetching and improving performance.

• With using interceptor (name: UseRepositoryInterceptor) and paramDecorator (name: GraphQLQueryToOption)

• You can find example code in /src/user/user.resolver.ts

The permission guard is used to block access to specific fields in client requests.

• In GraphQL, clients can request any field, which could expose sensitive information. This guard ensures that sensitive fields are protected.

• It allows controlling access to specific fields based on the server's permissions.

@Query(()=>Some)
@UseQueryPermissionGuard(Some, { something: true })
async getManySomeList(){
  return this.someService.getMany()
}

With this API, if the client request includes the field "something," a Forbidden error will be triggered.

There might be duplicate code when using this guard alongside other interceptors(name: UseRepositoryInterceptor) in this boilerplate. In such cases, you may need to adjust the code to ensure compatibility.

Based on the GraphQL status code standard, we write status codes accordingly. You can see more details here.

To make most of GraphQL's advantage, We created its own api, such as GetMany or GetOne. We tried to make it as comfortable as possible, but if you find any mistakes or improvements, please point them out or promote them.

You can see detail in folder /src/common/graphql files

// query
query($input:GetManyInput) {
  getManyPlaces(input:$input){
    data{
      id
      longitude
      count
    }
  }
}

// variables
{
  input: {
    pagination: {
      size: 10,
      page: 0, // Started from 0
    },
    order: { id: 'DESC' },
    dataType: 'data', //all or count or data - default: all
    where: {
      id: 3,
    },
  },
};

You can see detail here.

There is CRUD Generator in NestJS. In this repository, It has its own generator with plopjs. You can use like below.

$ yarn g

This project provides a custom decorator that makes it easy to implement method caching in NestJS applications.

1. Caching Functionality: Utilizes DiscoveryService and MetadataScanner to handle method caching automatically at runtime.
2. Usage: Designed for use with any provider.
3. GraphQL Resolvers: Resolvers are also part of providers, but due to GraphQL's internal logic, method overrides do not work. Therefore, the functionality has been replaced with an interceptor.

@Injectable()
export class ExampleService {
  @Cache(...)
  async exampleMethod(...args: unknown) {
    ...
  }
}

You can find related codes here

@nestjs/testing = supertest + jest

Before starting the test, you need to set at least jwt-related environment variables in an env file named .test.env.

Unit test(with jest mock) for services & resolvers (*.service.spec.ts & *.resolver.spec.ts)

$ yarn test:unit

Integration test(with pg-mem) for modules (*.module.spec.ts)

$ yarn test:integration

E2E Test(with docker container)

$ yarn test:e2e:docker

To ensure github actions execution, please set the 'ENV' variable within your github actions secrets as your .test.env configuration.

Note: Github Actions does not recognize newline characters. Therefore, you must remove any newline characters from each environment variable value in your .env file, ensuring that the entire content is on a single line when setting the Secret. If you need to use an environment variable value that includes newline characters, encode the value using Base64 and store it in the Github Secret, then decode it within the workflow.

ex)

JWT_PRIVATE_KEY= -----BEGIN RSA PRIVATE KEY-----...MIIEogIBAAKCAQBZ...-----END RSA PRIVATE KEY-----

$ yarn prepare

You can check detail here

Before commit, The pre-commit hooks is executed.

Lint checks have been automated to run before a commit is made.

If you want to add test before commit actions, you can add follow line in pre-commit file.

...
yarn test
...

You can check detail here

The pre-push hooks is executed before the push action.

The default rule set in the pre-push hook is to prevent direct pushes to the main branch.

If you want to enable this action, you should uncomment the lines in the pre push file.

SWC (Speedy Web Compiler) is an extensible Rust-based platform that can be used for both compilation and bundling. Using SWC with Nest CLI is a great and simple way to significantly speed up your development process.

After applying SWC, the following error was displayed in jest using an in-memory database (pg-mem):

    QueryFailedError: ERROR: function obj_description(regclass,text) does not exist
    HINT: 🔨 Please note that pg-mem implements very few native functions.

                👉 You can specify the functions you would like to use via "db.public.registerFunction(...)"

    🐜 This seems to be an execution error, which means that your request syntax seems okay,
        but the resulting statement cannot be executed → Probably not a pg-mem error.

    *️⃣ Failed SQL statement: SELECT "table_schema", "table_name", obj_description(('"' || "table_schema" || '"."' || "table_name" || '"')::regclass, 'pg_class') AS table_comment FROM "information_schema"."tables" WHERE ("table_schema" = 'public' AND "table_name" = 'user');

    👉 You can file an issue at https://github.com/oguimbal/pg-mem along with a way to reproduce this error (if you can), and  the stacktrace:

pg-mem is a library designed to emulate PostgreSQL, however, it does not support all features, which is why the above error occurred.

This error can be resolved by implementing or overriding existing functions. Below is the function implementation for the resolution. Related issues can be checked here.

db.public.registerFunction({
  name: 'obj_description',
  args: [DataType.text, DataType.text],
  returns: DataType.text,
  implementation: () => 'test',
});

• TDD

  • Unit Test (Use mock)
  • Integration Test (Use in-memory DB)
  • End To End Test (Use docker)

• CI

  • Github actions
  • husky

• GraphQL Upload

• Healthcheck

• Divide usefactory

• SWC Compiler

• Refresh Token

• Caching

• Graphql Subscription

• Remove lodash

• CASL

MIT