introduction
General-purpose compiler extension for type-safe routes and message keys, currently tested with NestJS.
What is Duck Gen?
Duck Gen is a general-purpose compiler extension in the @gentleduck ecosystem. It scans server code and emits TypeScript definitions that describe API routes and message keys. It is designed for multiple frameworks and is currently being tested with NestJS. The goal is simple: keep server contracts and client types aligned without manual sync work.
If you have ever shipped a client without matching route types or drifted i18n keys, Duck Gen removes that pain.
Duck Gen is like a translator that reads your server code and writes a dictionary your client can use. Every time the server changes, you re-run the translator and your client instantly knows the new vocabulary.
The Human Behind the Duck
@wildduck2 is the architect behind @gentleduck. He's not interested in building another abandoned open-source graveyard. He's obsessed with creating tools that developers actually want to use performant, maintainable, and battle-tested in production environments.
He's also criminally responsive to community feedback. Got a bug? It gets fixed. Got a feature request that makes sense? It gets seriously considered. No corporate bureaucracy, no waiting three quarters for a minor patch. Just direct, honest development.
The entire @gentleduck organization exists because modern web development shouldn't feel like assembling IKEA furniture in the dark. Every library, every tool, every decision is made with one question: "Does this actually help developers ship better products faster?"
Why Duck Gen Exists
Typed routes and message keys should not be a manual chore. As a general-purpose compiler extension, Duck Gen automates the contract layer so you can focus on building features.
What you actually get:
- Typed routes, end to end: Generate request and response types directly from framework controllers (currently tested with NestJS).
- Message key safety: Keep i18n dictionaries aligned with the constants you declare in code.
- Configurable scanning: Point Duck Gen at your
tsconfig.jsonand let its include/exclude globs define the scan surface. - Warnings with intent: Duck Gen surfaces duplicate message const names and
anyreturns so you can fix contracts early. - Built for automation: Run it locally or in CI. Generated files are safe to overwrite.
Duck Gen only produces .d.ts files, pure type declarations. There is no runtime
library, no bundle size impact, no performance overhead. Types are erased at compile time.
Documentation map
| Section | What it covers |
|---|---|
| Installation | Install Duck Gen + Duck Query and generate your first types. |
| Duck Gen | How Duck Gen works, quick start, output, and troubleshooting. |
| Configuration | Every duck-gen.json option explained. |
| API Routes | How controllers are scanned, supported decorators, request shapes. |
| Messages | How @duckgen tags work, group keys, i18n patterns. |
| Generated Types | Every exported type with usage examples. |
| Duck Query | Type-safe Axios client overview. |
| Client Methods | Detailed reference for every client method. |
| Query Types | Duck Query types for custom route maps. |
| Advanced | Interceptors, error handling, React Query, patterns. |
| End-to-End Guide | Complete walkthrough from NestJS backend to typed client. |
| Templates | Full auth example with DTOs, messages, and Duck Query. |
| FAQs | Common questions and answers. |
| Course | Step-by-step tutorial from zero to production-ready type safety. |
If you are completely new, start with the Course for a guided walkthrough. If you want to jump straight in, head to the Installation guide. If you want to understand the system first, start with Duck Gen overview.
Getting Started (The Fast Version)
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"
}
}
}bunx duck-genimport type { RouteReq, RouteRes } from '@gentleduck/gen/nestjs'See the Duck Gen core guide for full configuration and usage, or jump straight to the end-to-end guide for a complete walkthrough.
Contributing
We want your contributions. Bug reports, feature requests, code, documentation improvements, hot takes on generator ergonomics bring it all to our GitHub repository.
Unlike projects run by committees, we move fast. Good ideas get implemented. Bad ideas get respectfully declined with actual reasoning. Contributions get reviewed by humans who remember what it's like to be on the other side of a pull request.
The @gentleduck community is built on mutual respect and the shared understanding that we're all just trying to build cool stuff without losing our minds.