strict mode & webpack

Two settings that shape boot-time behavior: one for CI, the other about an architectural limitation.

strict: true

Pass { strict: true } to forRoot() so the app throws on startup when any controller with @WithDocs() has no companion file. Recommended for CI, where failing fast is preferable to a silently incomplete OpenAPI document.

ts
DocfyModule.forRoot({ strict: true });

webpack: true

DocfyModule's runtime discovery does not work here

If your nest-cli.json has "webpack": true under compilerOptions, DocfyModule's runtime pipeline (@WithDocs() + require.cache discovery) will not work, and there is no configuration that makes it work. This is architectural, and it has two causes:

First, webpack bundles every module into a single bundle file and never populates Node's require.cache with one entry per original source file, which is what the discovery mechanism depends on. You'll see Could not locate source file for X for every controller with @WithDocs().

Second, even working around that lookup, there's a second, unavoidable barrier: a docs file loaded via require() from outside the bundle creates a class object structurally different from the one the running application actually uses internally. Decorating that isolated copy has no effect whatsoever on the document that SwaggerModule.createDocument() actually serves, and this happens silently, with no error.

Two ways to get full docs anyway, in order of preference:

  • The CLI plugin (recommended): fixes it at the root, automatically, on every build, using the same mechanism @nestjs/swagger's own CLI plugin uses. See The CLI plugin.
  • Use patch-spec: a manual, CI-driven static patch of an already-built OpenAPI document, with no dependency on require.cache. See CLI: patch-spec and patch-spec: manual alternative.
What about the SWC builder?

None of this applies to "builder": "swc" — SWC still compiles one file per module, so require.cache gets populated the same way tsc does, and DocfyModule's runtime discovery works normally there. The only SWC-specific detail is unrelated to this limitation: registering the CLI plugin under SWC needs "typeCheck": true, covered in the plugin guide's SWC builder section.