{"id":30740968,"url":"https://github.com/itsdevdom/ncc-nestjs-swagger-setup","last_synced_at":"2025-09-04T00:17:50.696Z","repository":{"id":56468273,"uuid":"252228189","full_name":"itsdevdom/ncc-nestjs-swagger-setup","owner":"itsdevdom","description":"Setup for a NestJS application that uses Swagger, built with ncc","archived":false,"fork":false,"pushed_at":"2020-11-05T16:22:00.000Z","size":179,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-20T21:07:28.785Z","etag":null,"topics":["build","ncc","nestjs","nestjs-swagger","swagger","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/itsdevdom.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}},"created_at":"2020-04-01T16:25:15.000Z","updated_at":"2024-03-14T14:54:00.000Z","dependencies_parsed_at":"2022-08-15T19:20:29.360Z","dependency_job_id":null,"html_url":"https://github.com/itsdevdom/ncc-nestjs-swagger-setup","commit_stats":null,"previous_names":["itsdevdom/ncc-nestjs-swagger-setup","dominique-mueller/ncc-nestjs-swagger-setup"],"tags_count":0,"template":false,"template_full_name":"itsdevdom/node-typescript-nestjs-starter","purl":"pkg:github/itsdevdom/ncc-nestjs-swagger-setup","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsdevdom%2Fncc-nestjs-swagger-setup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsdevdom%2Fncc-nestjs-swagger-setup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsdevdom%2Fncc-nestjs-swagger-setup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsdevdom%2Fncc-nestjs-swagger-setup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itsdevdom","download_url":"https://codeload.github.com/itsdevdom/ncc-nestjs-swagger-setup/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsdevdom%2Fncc-nestjs-swagger-setup/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273530638,"owners_count":25122031,"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","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["build","ncc","nestjs","nestjs-swagger","swagger","typescript"],"created_at":"2025-09-04T00:17:48.509Z","updated_at":"2025-09-04T00:17:50.675Z","avatar_url":"https://github.com/itsdevdom.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# ncc-nestjs-swagger-setup\n\n**Setup for a [NestJS](https://github.com/nestjs/nest) application that uses [Swagger](https://github.com/nestjs/swagger), built with [ncc](https://github.com/vercel/ncc)\n\u003cbr\u003e\n(based on my [Node NestJS TypeScript Starter](https://github.com/dominique-mueller/node-nestjs-typescript-starter) project)**\n\n\u003c/div\u003e\n\n\u003cbr\u003e\u003cbr\u003e\n\n## How to make NestJS Swagger work with ncc\n\n### 1. Install Swagger-related dependencies\n\nMake sure that all relevant dependencies are installed. We need ALL the Swagger-related dependencies, even if we don't actually use them.\nWeird, I know.\n\nSo, within your `package.json` file:\n\n```diff\n  {\n    \"dependencies\": {\n+     \"@nestjs/swagger\": \"4.5.x\",\n+     \"fastify-swagger\": \"2.5.x\",\n+     \"swagger-ui-express\": \"4.1.x\"\n    }\n  }\n```\n\n\u003cbr\u003e\n\n### 2. Update bootstrap function to serve static assets properly\n\nRight now, we can navigate to the Swagger page (at **[http://localhost:3000/swagger](http://localhost:3000/swagger)**) but we get a bunch of\nerrors telling us that static assets (stylesheets, images, ...) couldn't be fetched properly.\n\n`ncc` is very intelligent - it not only bundles up all imports but it also recognizes files being read by the application during runtime\n(e.g. via `fs.readFile`) and copies them over into the build output folder (specifically, into the `build/static` folder). The\n**[NestJS Swagger](https://github.com/nestjs/swagger)** implementation relies on\n**[Swagger UI Express](https://github.com/scottie1984/swagger-ui-express)** which itself - sadly - reads stuff from the file system during\nruntime, such as HTML templates (see **[Issue #114](https://github.com/scottie1984/swagger-ui-express/issues/114)**). So, `ncc` will copy\nthose files over into our `build/static` folder. This, however, is something our application currently does not expect.\n\nTo fix the issue, we tell our NestJS application to serve the files from within the `build/static` folder when requesting them from the\n`/swagger` URL. So within your `main.ts` file:\n\n```diff\n  // Create application\n- const app: INestApplication = await NestFactory.create(AppModule);\n+ const app: NestExpressApplication = await NestFactory.create(AppModule);\n\n  // Configure Swagger\n  const options = new DocumentBuilder()\n    .setTitle(\"Hello World API - Swagger\")\n    .setDescription(\"REST API description\")\n    .build();\n  const document = SwaggerModule.createDocument(app, options);\n  SwaggerModule.setup(\"/swagger\", app, document);\n\n+ // WORKAROUND:\n+ // We serve the \"static\" folder (generated by \"ncc\") behind the \"/swagger\" URL so that all Swagger UI assets get fetched properly\n+ app.useStaticAssets(join(__dirname, \"/static\"), {\n+   prefix: \"/swagger\"\n+ });\n```\n\n\u003cbr\u003e\n\n### Step 3: Enjoy Swagger\n\nNow, Swagger is ready and running at **[http://localhost:3000/swagger](http://localhost:3000/swagger)**.\n\n\u003cbr\u003e\u003cbr\u003e\n\n## Commands\n\nThe following commands are available:\n\n| Command               | Description                                        | CI                 |\n| --------------------- | -------------------------------------------------- | ------------------ |\n| `npm start`           | Creates a development build, running in watch mode |                    |\n| `npm run build`       | Creates a production build                         | :heavy_check_mark: |\n| `npm run start:build` | Runs a production build                            |                    |\n| `npm run test`        | Executes all unit tests                            | :heavy_check_mark: |\n| `npm run test:watch`  | Executes all unit tests, running in watch mode     |                    |\n\n\u003e Note that linters are not part of this template, you might want to add and configure them yourself!\n\n#### Build \u0026 Test Output\n\nThe `build` command will output the result into the `build` folder, the application itself will be put at `build/index.js`. The test\ncoverage will be put into the `coverage` folder.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsdevdom%2Fncc-nestjs-swagger-setup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitsdevdom%2Fncc-nestjs-swagger-setup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsdevdom%2Fncc-nestjs-swagger-setup/lists"}