Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dominique-mueller/ncc-nestjs-swagger-setup
Setup for a NestJS application that uses Swagger, built with ncc
https://github.com/dominique-mueller/ncc-nestjs-swagger-setup
build ncc nestjs nestjs-swagger swagger typescript
Last synced: 2 months ago
JSON representation
Setup for a NestJS application that uses Swagger, built with ncc
- Host: GitHub
- URL: https://github.com/dominique-mueller/ncc-nestjs-swagger-setup
- Owner: dominique-mueller
- License: mit
- Created: 2020-04-01T16:25:15.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2020-11-05T16:22:00.000Z (about 4 years ago)
- Last Synced: 2024-10-12T08:24:01.706Z (3 months ago)
- Topics: build, ncc, nestjs, nestjs-swagger, swagger, typescript
- Language: TypeScript
- Homepage:
- Size: 175 KB
- Stars: 7
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ncc-nestjs-swagger-setup
**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)
(based on my [Node NestJS TypeScript Starter](https://github.com/dominique-mueller/node-nestjs-typescript-starter) project)**
## How to make NestJS Swagger work with ncc
### 1. Install Swagger-related dependencies
Make sure that all relevant dependencies are installed. We need ALL the Swagger-related dependencies, even if we don't actually use them.
Weird, I know.
So, within your `package.json` file:
```diff
{
"dependencies": {
+ "@nestjs/swagger": "4.5.x",
+ "fastify-swagger": "2.5.x",
+ "swagger-ui-express": "4.1.x"
}
}
```
### 2. Update bootstrap function to serve static assets properly
Right now, we can navigate to the Swagger page (at **[http://localhost:3000/swagger](http://localhost:3000/swagger)**) but we get a bunch of
errors telling us that static assets (stylesheets, images, ...) couldn't be fetched properly.
`ncc` is very intelligent - it not only bundles up all imports but it also recognizes files being read by the application during runtime
(e.g. via `fs.readFile`) and copies them over into the build output folder (specifically, into the `build/static` folder). The
**[NestJS Swagger](https://github.com/nestjs/swagger)** implementation relies on
**[Swagger UI Express](https://github.com/scottie1984/swagger-ui-express)** which itself - sadly - reads stuff from the file system during
runtime, such as HTML templates (see **[Issue #114](https://github.com/scottie1984/swagger-ui-express/issues/114)**). So, `ncc` will copy
those files over into our `build/static` folder. This, however, is something our application currently does not expect.
To fix the issue, we tell our NestJS application to serve the files from within the `build/static` folder when requesting them from the
`/swagger` URL. So within your `main.ts` file:
```diff
// Create application
- const app: INestApplication = await NestFactory.create(AppModule);
+ const app: NestExpressApplication = await NestFactory.create(AppModule);
// Configure Swagger
const options = new DocumentBuilder()
.setTitle("Hello World API - Swagger")
.setDescription("REST API description")
.build();
const document = SwaggerModule.createDocument(app, options);
SwaggerModule.setup("/swagger", app, document);
+ // WORKAROUND:
+ // We serve the "static" folder (generated by "ncc") behind the "/swagger" URL so that all Swagger UI assets get fetched properly
+ app.useStaticAssets(join(__dirname, "/static"), {
+ prefix: "/swagger"
+ });
```
### Step 3: Enjoy Swagger
Now, Swagger is ready and running at **[http://localhost:3000/swagger](http://localhost:3000/swagger)**.
## Commands
The following commands are available:
| Command | Description | CI |
| --------------------- | -------------------------------------------------- | ------------------ |
| `npm start` | Creates a development build, running in watch mode | |
| `npm run build` | Creates a production build | :heavy_check_mark: |
| `npm run start:build` | Runs a production build | |
| `npm run test` | Executes all unit tests | :heavy_check_mark: |
| `npm run test:watch` | Executes all unit tests, running in watch mode | |
> Note that linters are not part of this template, you might want to add and configure them yourself!
#### Build & Test Output
The `build` command will output the result into the `build` folder, the application itself will be put at `build/index.js`. The test
coverage will be put into the `coverage` folder.