gem-hunter
Language: TypeScript
NestJS + GraphQL + TypeORM + PostgresQL Boilerplate
NestJS boilerplate with TypeORM, GraphQL and PostgreSQL
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 installfor development
$ yarn dev # or npm run devfor 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 upIf 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
- The custom
typeormcommand defined inpackage.jsonis configured forNODE_ENV=production.- Migrations are intended for production use, while
typeorm synchronizeshould be used for development purposes.- You can see the detailed configuration code here
- 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" }
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)
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.
DiscoveryService and MetadataScanner to handle method caching automatically at runtime.@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
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
...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
CI
GraphQL Upload
Healthcheck
Divide usefactory
SWC Compiler
Refresh Token
Caching
Graphql Subscription
Remove lodash
MIT