Configuration

tsgonest supports both TypeScript and JSON configuration files. The recommended approach is tsgonest.config.ts with the defineConfig() helper for type safety and autocomplete.

TypeScript config (recommended)

import { defineConfig } from '@tsgonest/runtime';

export default defineConfig({
  controllers: {
    include: ['src/**/*.controller.ts'],
  },
  transforms: {
    validation: true,
    serialization: true,
  },
  openapi: {
    output: 'dist/openapi.json',
  },
});

The defineConfig() helper provides full IntelliSense — autocomplete, inline documentation, and type checking for every field.

JSON config (alternative)

If you prefer JSON, create tsgonest.config.json in your project root:

{
  "controllers": {
    "include": ["src/**/*.controller.ts"]
  },
  "transforms": {
    "validation": true,
    "serialization": true
  },
  "openapi": {
    "output": "dist/openapi.json"
  }
}

Config resolution

tsgonest resolves configuration in this order:

1. --config CLI flag (explicit path)
2. tsgonest.config.ts in the working directory
3. tsgonest.config.json in the working directory
4. Default configuration (sensible defaults)

Full configuration reference

import { defineConfig } from '@tsgonest/runtime';

export default defineConfig({
  controllers: {
    include: ['src/**/*.controller.ts'],
    exclude: ['src/**/*.spec.ts'],
  },
  transforms: {
    validation: true,
    serialization: true,
  },
  openapi: {
    output: 'dist/openapi.json',
    title: 'My API',
    version: '1.0.0',
    description: 'My NestJS API documentation',
  },
});

For the full set of OpenAPI metadata fields (contact, license, servers, security schemes), NestJS settings (global prefix, versioning), and dev/build settings — see the field reference below.

Full Type Reference

Field reference

controllers

Controls which files are analyzed for NestJS controller routes (used for OpenAPI generation and route mapping).

If an included file contains unsupported dynamic patterns (runtime-generated controllers or dynamic decorator path args), tsgonest emits warnings and excludes those routes from OpenAPI.

import { defineConfig } from '@tsgonest/runtime';

export default defineConfig({
  controllers: {
    include: ['src/**/*.controller.ts'],
    exclude: ['src/**/*.spec.ts', 'src/**/health.controller.ts'],
  },
  // ...
});

transforms

Controls companion file generation (validators and serializers).

import { defineConfig } from '@tsgonest/runtime';

export default defineConfig({
  transforms: {
    validation: true,
    serialization: true,
    include: ['src/**/*.dto.ts'],
    exclude: ['LegacyUserDto', 'Internal*'],
  },
  // ...
});

openapi

Controls OpenAPI document generation.

For detailed OpenAPI metadata configuration (contact, license, servers, security schemes), see the OpenAPI Config page.

nestjs

NestJS-specific settings that affect how routes are generated in the OpenAPI document.

nestjs.versioning

import { defineConfig } from '@tsgonest/runtime';

export default defineConfig({
  // ...
  nestjs: {
    globalPrefix: 'api',
    versioning: {
      type: 'URI',
      defaultVersion: '1',
      prefix: 'v',
    },
  },
});

With this config, a @Controller('users') with a @Get() method produces the path /api/v1/users in the OpenAPI document. See the Versioning page for details.

sdk

TypeScript SDK generation settings. Run tsgonest sdk after building to generate a typed client from your OpenAPI spec.

import { defineConfig } from '@tsgonest/runtime';

export default defineConfig({
  // ...
  sdk: {
    output: './sdk',
    input: 'dist/openapi.json', // optional — defaults to openapi.output
  },
});

See the SDK Generation page for full documentation.

Dev/build settings

These fields mirror NestJS CLI conventions for easy migration:

Validation rules

tsgonest validates your config file and reports errors for:

• controllers.include must contain at least one glob pattern
• openapi.output must not be empty
• openapi.output must have a .json extension

Path resolution

• Relative paths in openapi.output are resolved relative to the config file's directory
• If --config is not set, tsgonest looks for tsgonest.config.ts first, then tsgonest.config.json
• If no config file exists and --config is not set, tsgonest uses sensible defaults

Migration from nest-cli.json

If you're migrating from nest-cli.json, here's a mapping of common fields: