De CLI-plugin

Dit is hetzelfde mechanisme dat de eigen CLI-plugin van @nestjs/swagger gebruikt om onder webpack: true te werken. Daarom is @ApiProperty() niet vereist op elke DTO-property, zelfs niet in een webpack-build. De Nest CLI voedt een TypeScript-compilerplugin-hook (compilerOptions.plugins) identiek naar zowel de tsc</4- als de webpack-builder (ts-loader).

Registreer de plugin

Registreer nestjs-docfy in nest-cli.json:

{
  "compilerOptions": {
    "webpack": true,
    "plugins": ["nestjs-docfy"]
  }
}

import { applyDocfyMetadata } from 'nestjs-docfy';

const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api', app, applyDocfyMetadata(document));

Automatische detectie

De plugin vergeten te registreren is makkelijk over het hoofd te zien tot een build zonder documentatie uitgaat, dus checkt elke generate-run al nest-cli.json en print een waarschuwing wanneer webpack: true staat zonder de plugin. Geef --register-plugin mee om dat automatisch te laten repareren in plaats van het bestand met de hand te bewerken:

npx nestjs-docfy generate --register-plugin

Dit is bewust opt-in, want sommige teams houden bewust vast aan patch-spec in plaats van een compilerplugin, dus bewerkt generate nest-cli.json nooit tenzij je daar expliciet om vraagt. Het voegt toe aan een bestaande compilerOptions.plugins-array (herkent zowel string- als objectvorm-entries als al geregistreerd) en respecteert --dry-run.

Hoe het werkt

De plugin van nestjs-docfy herschrijft geen decoratorsyntax en raakt de AST helemaal niet aan. Bij elke compilatie draait ze exact dezelfde statische analyse die generate/check/patch-spec al doen (via ts-morph, tegen de bronboom, niet de bundel) en schrijft ze de resulterende patch naar docfy-metadata.json naast de build-output.

Daarna, meteen na SwaggerModule.createDocument(), leest applyDocfyMetadata() dat bestand en voegt het samen. Er komt geen require.cache bij kijken en geen probleem met gebundelde class-identiteit, want het heeft de draaiende app nooit nodig om iets te berekenen.

vs. patch-spec

SWC-builder

@nestjs/cli behandelt de SWC-builder anders. Het roept before() onder "builder": "swc" nooit aan, alleen een ReadonlyVisitor, en dat ook alleen als "typeCheck": true ook is ingesteld (anders slaat SWC typecontrole gewoon zelf over). Deze plugin exporteert beide hooks, dus die instelling aanzetten is alles wat nodig is:

{
  "compilerOptions": {
    "builder": "swc",
    "typeCheck": true,
    "plugins": ["nestjs-docfy"]
  }
}

Niets hiervan raakt de runtime discovery van DocfyModule. Die werkt onder SWC precies zoals onder tsc, want SWC compileert nog steeds één bestand per module, waardoor require.cache op dezelfde manier gevuld raakt. Is typeCheck instellen geen optie, dan brengen @WithDocs() samen met DocfyModule.forRoot() je er ook zonder de plugin.