duck gen

What is Duck Gen?

Duck Gen is a compiler extension that reads your server source code and generates TypeScript definition files (.d.ts) for every API route and message key it finds. It removes the step of writing route types by hand to match the server.

Duck Gen ships with a NestJS adapter. The architecture supports multiple frameworks; NestJS is the first one.

The problem it solves

Without Duck Gen, keeping client types aligned with server routes looks like this:

// Server: you add a new route
@Post('signup')
signup(@Body() body: SignupDto): Promise<AuthSession> { ... }
 
// Client: you manually write the matching types... or forget to
type SignupReq = { email: string; password: string } // hope this matches SignupDto
type SignupRes = { token: string } // hope this matches AuthSession

// Server: you add a new route
@Post('signup')
signup(@Body() body: SignupDto): Promise<AuthSession> { ... }
 
// Client: you manually write the matching types... or forget to
type SignupReq = { email: string; password: string } // hope this matches SignupDto
type SignupRes = { token: string } // hope this matches AuthSession

Every time a DTO changes or a new route is added, someone has to update the client types. Duck Gen removes that step.

What it generates

Duck Gen produces two categories of types:

Both outputs are .d.ts files you import directly. No runtime cost.

How it works

Here is the step-by-step flow:

1. Load config: Duck Gen reads duck-gen.json from your project root. This tells it which framework adapter to use, where your tsconfig.json lives, and what to generate.

2. Build the project: Using ts-morph, it creates an in-memory TypeScript project from your tsconfigPath. The include and exclude globs in your tsconfig.json determine which files get scanned.

3. Scan source files: The NestJS adapter looks for:

   • Classes decorated with @Controller(), these become API routes.
   • Exported variables with @duckgen JSDoc tags, these become message sources.

4. Extract type information: For each controller method, Duck Gen extracts:

   • The HTTP method (GET, POST, etc.) from decorators.
   • The full route path (globalPrefix + controller path + method path).
   • Request shape from parameter decorators (@Body, @Query, @Param, @Headers).
   • Response type from the method's return type.

5. Emit .d.ts files: Generated type files are written to the package's generated folder and optionally to custom output directories.

Quick start

bun add -d @gentleduck/gen

bun add -d @gentleduck/gen

{
  "$schema": "node_modules/@gentleduck/gen/duck-gen.schema.json",
  "framework": "nestjs",
  "extensions": {
    "shared": {
      "includeNodeModules": false,
      "outputSource": "./generated",
      "sourceGlobs": ["src/**/*.ts", "src/**/*.tsx"],
      "tsconfigPath": "./tsconfig.json"
    },
    "apiRoutes": {
      "enabled": true,
      "globalPrefix": "/api",
      "normalizeAnyToUnknown": true,
      "outputSource": "./generated"
    },
    "messages": {
      "enabled": true,
      "outputSource": "./generated"
    }
  }
}

{
  "$schema": "node_modules/@gentleduck/gen/duck-gen.schema.json",
  "framework": "nestjs",
  "extensions": {
    "shared": {
      "includeNodeModules": false,
      "outputSource": "./generated",
      "sourceGlobs": ["src/**/*.ts", "src/**/*.tsx"],
      "tsconfigPath": "./tsconfig.json"
    },
    "apiRoutes": {
      "enabled": true,
      "globalPrefix": "/api",
      "normalizeAnyToUnknown": true,
      "outputSource": "./generated"
    },
    "messages": {
      "enabled": true,
      "outputSource": "./generated"
    }
  }
}

bunx duck-gen

bunx duck-gen

Config loaded
Processing done

Config loaded
Processing done

import type { ApiRoutes, RouteReq, RouteRes } from '@gentleduck/gen/nestjs'
 
// Now your client knows every route, request shape, and response type
type SigninRequest = RouteReq<'/api/auth/signin'>
type SigninResponse = RouteRes<'/api/auth/signin'>

import type { ApiRoutes, RouteReq, RouteRes } from '@gentleduck/gen/nestjs'
 
// Now your client knows every route, request shape, and response type
type SigninRequest = RouteReq<'/api/auth/signin'>
type SigninResponse = RouteRes<'/api/auth/signin'>

Output files

Duck Gen always writes to the package's generated folder:

node_modules/@gentleduck/gen/
  generated/
    nestjs/
      duck-gen-api-routes.d.ts   # route types
      duck-gen-messages.d.ts     # message types
      index.d.ts                 # barrel export
    index.d.ts                   # top-level barrel

node_modules/@gentleduck/gen/
  generated/
    nestjs/
      duck-gen-api-routes.d.ts   # route types
      duck-gen-messages.d.ts     # message types
      index.d.ts                 # barrel export
    index.d.ts                   # top-level barrel

If you set outputSource in your config, Duck Gen also copies the generated files to those locations (e.g. ./generated in your project root).

Import paths:

// From the package entrypoint (recommended)
import type { ApiRoutes, RouteReq, RouteRes } from '@gentleduck/gen/nestjs'
 
// From a custom output directory
import type { ApiRoutes } from './generated/duck-gen-api-routes'

// From the package entrypoint (recommended)
import type { ApiRoutes, RouteReq, RouteRes } from '@gentleduck/gen/nestjs'
 
// From a custom output directory
import type { ApiRoutes } from './generated/duck-gen-api-routes'

CLI usage

Add a script to your package.json for convenience:

{
  "scripts": {
    "generate": "duck-gen",
    "generate:watch": "duck-gen --watch"
  }
}

{
  "scripts": {
    "generate": "duck-gen",
    "generate:watch": "duck-gen --watch"
  }
}

# Run directly
bunx duck-gen
 
# Or via script
bun run generate

# Run directly
bunx duck-gen
 
# Or via script
bun run generate

CLI behavior:

• Requires duck-gen.json in the current directory. Fails if missing.
• Overwrites existing generated files on every run. Safe to run repeatedly.
• Prints warnings for any return types and duplicate message const names.
• Deterministic output. Safe for CI/CD pipelines.

What to read next

Troubleshooting

Requirements

• Bun 1.3.5 or newer.
• A TypeScript project with a valid tsconfig.json.
• NestJS (for the current tested adapter).

Contributing

Duck Gen lives in the Gentleduck monorepo. Open issues and pull requests at @gentleduck.