{"id":14978633,"url":"https://github.com/catsmiaow/nestjs-project-structure","last_synced_at":"2025-05-14T19:09:32.007Z","repository":{"id":38408828,"uuid":"209524087","full_name":"CatsMiaow/nestjs-project-structure","owner":"CatsMiaow","description":"Node.js framework NestJS project structure","archived":false,"fork":false,"pushed_at":"2025-04-29T04:38:45.000Z","size":3957,"stargazers_count":1197,"open_issues_count":0,"forks_count":238,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-05-10T04:31:46.222Z","etag":null,"topics":["nest","nestjs","node","nodejs","project-structure","typeorm","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CatsMiaow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-09-19T10:19:41.000Z","updated_at":"2025-05-10T04:24:24.000Z","dependencies_parsed_at":"2023-12-08T08:30:54.197Z","dependency_job_id":"f85af720-9bfd-451a-960d-be5e2e66afd4","html_url":"https://github.com/CatsMiaow/nestjs-project-structure","commit_stats":{"total_commits":234,"total_committers":3,"mean_commits":78.0,"dds":0.008547008547008517,"last_synced_commit":"699f3be983f369d4f8f61b1c2ad03ce244038562"},"previous_names":["catsmiaow/node-nestjs-structure"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CatsMiaow%2Fnestjs-project-structure","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CatsMiaow%2Fnestjs-project-structure/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CatsMiaow%2Fnestjs-project-structure/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CatsMiaow%2Fnestjs-project-structure/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CatsMiaow","download_url":"https://codeload.github.com/CatsMiaow/nestjs-project-structure/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254209859,"owners_count":22032897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nest","nestjs","node","nodejs","project-structure","typeorm","typescript"],"created_at":"2024-09-24T13:58:04.187Z","updated_at":"2025-05-14T19:09:31.842Z","avatar_url":"https://github.com/CatsMiaow.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nestjs-project-structure\n\nNode.js framework NestJS project structure\n\u003e Started from this issue: [nestjs/nest#2249](https://github.com/nestjs/nest/issues/2249#issuecomment-494734673)\n\n## Alternatives\n\nIf you focus on the performance or features of the module, you can consider:\n\n- [Fastify](https://docs.nestjs.com/techniques/performance) instead of `Express`\n- [MikroORM](https://docs.nestjs.com/recipes/mikroorm) instead of `TypeORM`\n  - or [DrizzleORM](https://trilon.io/blog/nestjs-drizzleorm-a-great-match)\n  - or [Sequelize](https://docs.nestjs.com/techniques/database#sequelize-integration)\n  - or [Prisma](https://docs.nestjs.com/recipes/prisma)\n- [SWC](https://docs.nestjs.com/recipes/swc#swc) instead of `TypeScript compiler`\n- [Vitest](https://docs.nestjs.com/recipes/swc#vitest) instead of `Jest`\n- [ESM](https://nodejs.org/api/esm.html) instead of `CommonJS`\n\nCheck out the [nestjs-project-performance](https://github.com/CatsMiaow/nestjs-project-performance) repository for examples using this alternative.\n\n## Configuration\n\n1. Create a `.env` file\n    - Rename the [.env.sample](.env.sample) file to `.env` to fix it.\n2. Edit env config\n    - Edit the file in the [config](src/config)/envs folder.\n    - `default`, `development`, `production`, `test`\n\n## Installation\n\n```sh\n# 1. node_modules\nnpm ci\n# 2. When synchronize database from existing entities\nnpm run entity:sync\n# 2-1. When import entities from an existing database\nnpm run entity:load\n```\n\nIf you use multiple databases in `entity:load`, [modify them.](bin/entity.ts#L47-L48)\n\n## Development\n\n```sh\nnpm run start:dev\n# https://docs.nestjs.com/recipes/repl\nnpm run start:repl\n```\n\nRun [http://localhost:3000](http://localhost:3000)\n\n## Test\n\n```sh\nnpm test # exclude e2e\nnpm run test:e2e\n```\n\n## Production\n\n```sh\nnpm run lint\nnpm run build\n# define environment variable yourself.\n# NODE_ENV=production PORT=8000 NO_COLOR=true node dist/app\nnode dist/app\n# OR\nnpm start\n```\n\n## Folders\n\n```js\n+-- bin // Custom tasks\n+-- dist // Source build\n+-- public // Static Files\n+-- src\n|   +-- config // Environment Configuration\n|   +-- entity // TypeORM Entities\n|   +-- auth // Authentication\n|   +-- common // Global Nest Module\n|   |   +-- constants // Constant value and Enum\n|   |   +-- controllers // Nest Controllers\n|   |   +-- decorators // Nest Decorators\n|   |   +-- dto // DTO (Data Transfer Object) Schema, Validation\n|   |   +-- filters // Nest Filters\n|   |   +-- guards // Nest Guards\n|   |   +-- interceptors // Nest Interceptors\n|   |   +-- interfaces // TypeScript Interfaces\n|   |   +-- middleware // Nest Middleware\n|   |   +-- pipes // Nest Pipes\n|   |   +-- providers // Nest Providers\n|   |   +-- * // models, repositories, services...\n|   +-- shared // Shared Nest Modules\n|   +-- gql // GraphQL Structure\n|   +-- * // Other Nest Modules, non-global, same as common structure above\n+-- test // Jest testing\n+-- typings // Modules and global type definitions\n\n// Module structure\n// Add folders according to module scale. If it's small, you don't need to add folders.\n+-- src/greeter\n|   +-- * // folders\n|   +-- greeter.constant.ts\n|   +-- greeter.controller.ts\n|   +-- greeter.service.ts\n|   +-- greeter.module.ts\n|   +-- greeter.*.ts\n|   +-- index.ts\n```\n\nThis is the most basic structure to start a NestJS project. \\\nYou should choose the right architecture\u003csup\u003e[[1]](https://romanglushach.medium.com/c0f93b8a1b96)\u003c/sup\u003e (Layered, Clean, Onion, Hexagonal ...)\u003csup\u003e[[2]](https://gist.github.com/EliFuzz/8ab693db36ff33ead1445a43c3f0ef7e)\u003c/sup\u003e based on the size of your project.\n\n## Implements\n\n- See [bootstrap](src/app.ts), [app.module](src/app.module.ts)\n  - Database, Module Router, Static Files, Validation, Pino Logger\n- [Global Exception Filter](src/common/filters/exceptions.filter.ts)\n- [Global Logging Context Middleware](src/common/middleware/logger-context.middleware.ts)\n- [Custom Logger](src/config/logger.config.ts) with nestjs-pino\n- [Custom Decorators](src/debug) Example at Nest level\n- [Configuration](src/config)\n- [Authentication](src/auth) - JWT and Session login with Passport\n- [Role-based Guard](src/common/guards/roles.guard.ts)\n- Controller Routes\n  - [Auth Login](src/base/controllers/auth.controller.ts)\n  - [Sample](src/sample/controllers/sample.controller.ts) Parameter and [DTO](src/sample/dto/sample.dto.ts)\n  - [CRUD API](src/sample/controllers/crud.controller.ts) Sample\n- [Database Query](src/sample/providers/database.service.ts) Example\n- [Unit Test](src/sample/providers/crud.service.spec.ts)\n- [E2E Test](test/e2e)\n- [Shared Modules](src/shared) Example\n- [GraphQL Structure](src/gql) Example\n\n## Documentation\n\n```sh\n# APP, Compodoc\nnpm run doc #\u003e http://localhost:8080\n# API, Swagger - src/swagger.ts\nnpm run doc:api #\u003e http://localhost:8000/api\n```\n\n### File Naming for Class\n\n```ts\nexport class PascalCaseSuffix {} //= pascal-case.suffix.ts\n// Except for suffix, PascalCase to hyphen-case\nclass FooBarNaming {} //= foo-bar.naming.ts\nclass FooController {} //= foo.controller.ts\nclass BarQueryDto {} //= bar-query.dto.ts\n```\n\n### Interface Naming\n\n```ts\n// https://stackoverflow.com/questions/541912\n// https://stackoverflow.com/questions/2814805\ninterface User {}\ninterface CustomeUser extends User {}\ninterface ThirdCustomeUser extends CustomeUser {}\n```\n\n### Index Exporting\n\n```diff\n# It is recommended to place index.ts in each folder and export.\n# Unless it's a special case, it is import from a folder instead of directly from a file.\n- import { FooController } from './controllers/foo.controller';\n- import { BarController } from './controllers/bar.controller';\n+ import { FooController, BarController } from './controllers';\n# My preferred method is to place only one fileOrFolder name at the end of the path.\n- import { UtilService } from '../common/providers/util.service';\n+ import { UtilService } from '../common';\n```\n\n#### Circular dependency\n\n\u003chttps://docs.nestjs.com/fundamentals/circular-dependency\u003e\n\n```diff\n# Do not use a path that ends with a dot.\n- import { FooService } from '.';\n- import { BarService } from '..';\n+ import { FooService } from './foo.service';\n+ import { BarService } from '../providers';\n```\n\n### Variables Naming\n\n\u003e refer to [Naming cheatsheet](https://github.com/kettanaito/naming-cheatsheet)\n\n### Links\n\n- [Better Nodejs Project](https://github.com/CatsMiaow/better-nodejs-project)\n- [Monorepo with npm Workspaces](https://github.com/CatsMiaow/node-monorepo-workspaces)\n- [Nest Project Performance](https://github.com/CatsMiaow/nestjs-project-performance)\n- [NestJS](https://docs.nestjs.com)\n  - [Nest Sample](https://github.com/nestjs/nest/tree/master/sample)\n  - [Awesome Nest](https://github.com/nestjs/awesome-nestjs)\n- [TypeORM](https://typeorm.io)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatsmiaow%2Fnestjs-project-structure","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcatsmiaow%2Fnestjs-project-structure","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatsmiaow%2Fnestjs-project-structure/lists"}