Skip to main content
Search...

faqs

Frequently asked questions about Duck Gen, its config, and generated output.

This FAQ focuses on Duck Gen usage, configuration, and generated output. If you cannot find what you need, open an issue or discussion on GitHub: https://github.com/gentleeduck/duck-ui




What is Duck Gen?

Duck Gen is a general-purpose compiler extension that scans server code and generates TypeScript definitions for API routes and message keys. It keeps server contracts and client types aligned without manual sync work.

What does Duck Gen generate?

It generates:

  • API route types (request/response shapes per route).
  • Message registry types from @duckgen message tags.
Which frameworks are supported?

Duck Gen is designed for multiple frameworks and is currently tested with NestJS. Only nestjs is accepted today; other values fail config validation.

What are the requirements?

You need:

  • Node 22 or newer.
  • A TypeScript project with a valid tsconfig.json.
  • NestJS if you are using the current tested adapter.
How do I install and run Duck Gen?

Install the package and run the CLI:

bun add -d @gentleduck/gen
bunx duck-gen
Where does the configuration live?

Duck Gen reads duck-gen.json from your project root. All paths inside the config are resolved relative to that file.

Do I need a config file?

Yes. duck-gen.json is required, and the CLI fails if it cannot read it. Use it to set required extension flags and paths.

Where do the generated types go?

Duck Gen writes generated files inside the package by default:

  • @gentleduck/gen/generated/nestjs/duck-gen-api-routes.d.ts
  • @gentleduck/gen/generated/nestjs/duck-gen-messages.d.ts
  • @gentleduck/gen/generated/nestjs/index.d.ts

Outputs always include the package generated folder. Add extra outputs with extensions.apiRoutes.outputSource and extensions.messages.outputSource, or set extensions.shared.outputSource for shared output dirs.

How do I import the generated types?

Import from the framework entrypoint:

import type { RouteReq, RouteRes, ApiRoutes, DuckGenI18nMessages, DuckgenScopedI18nByGroup } from '@gentleduck/gen/nestjs'
How do I control what Duck Gen scans?

Set extensions.shared.tsconfigPath and extensions.shared.includeNodeModules. The current NestJS adapter follows your tsconfig.json include/exclude globs; sourceGlobs and per-extension overrides are present in the schema but not applied yet.

Can I disable API routes or messages generation?

Yes. Set extensions.apiRoutes.enabled or extensions.messages.enabled to false in duck-gen.json.

What does globalPrefix do?

It prepends a shared base path (like /api) to all generated routes so your client types match your server prefix.

Why are no routes generated?

Common causes:

  • Your route decorators use dynamic values instead of string literals.
  • Your tsconfigPath is incorrect.
  • Your tsconfig.json include/exclude globs skip the files.
Why are message keys just string?

Add as const to your message arrays so Duck Gen can infer literal types.

How do I deal with any warnings?

Add explicit return types to your controller methods, or enable normalizeAnyToUnknown so generated types avoid any.

Is it safe to run Duck Gen in CI?

Yes. The generator overwrites the same output files every run, so it is safe to run repeatedly in CI or as part of your build.

Does Duck Gen modify my source code?

No. It reads your source and writes generated .d.ts files to the package output location.

I still have issues. Where should I ask for help?

Open an issue or discussion with your environment details and a small reproduction:

https://github.com/gentleeduck/duck-ui
Templateswhoiam