gentleeduck/duck-ui / skills/duck-gen
duck-gen
VerifiedUse when working with @gentleduck/gen, the type-safe API route and message code generator for TypeScript. Covers duck-gen.json configuration, NestJS controller scanning, API route type map generation, @duckgen message tagging, i18n type emission, the duck-gen CLI, and the @gentleduck/query typed Axios client.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.4 KB |
SKILL.md
View on GitHub---
name: duck-gen
description: >-
Use when working with @gentleduck/gen, the type-safe API route and message code
generator for TypeScript. Covers duck-gen.json configuration, NestJS controller
scanning, API route type map generation, @duckgen message tagging, i18n type
emission, the duck-gen CLI, and the @gentleduck/query typed Axios client.
allowed-tools: Read Grep Glob
argument-hint: "[extension-or-topic]"
---
# @gentleduck/gen
You are an expert on duck-gen, the compile-time code generation toolchain for the gentleduck ecosystem. Your scope covers `packages/duck-gen/` (the generator), `packages/duck-query/` (the typed client), and `packages/duck-ttest/` (type testing).
## Architecture Overview
duck-gen is a CLI tool that reads a `duck-gen.json` config, scans a TypeScript project using ts-morph, and emits `.d.ts` type declaration files. It has two main extensions:
1. **API Routes** -- scans NestJS controllers and emits a typed route map (`ApiRoutes` interface)
2. **Messages** -- scans `@duckgen`-tagged const exports and emits i18n type dictionaries
The generated types power `@gentleduck/query`, a typed Axios client that enforces request/response shapes at compile time.
## Package Map
| Package | npm | Purpose |
|---|---|---|
| `packages/duck-gen/` | `@gentleduck/gen` | CLI + code generator |
| `packages/duck-query/` | `@gentleduck/query` | Typed Axios client consuming generated types |
| `packages/duck-ttest/` | `@gentleduck/ttest` | Compile-time type testing utilities |
| `apps/duck-gen-docs/` | private | Documentation site (Next.js + MCP server) |
## Source Structure
```
packages/duck-gen/
bin/duck-gen.js # CLI entry (bun shim)
src/
index.ts # CLI runner: loads config, resolves outputs, runs processor
config/
index.ts # Barrel re-export
config.dto.ts # Zod schema for duck-gen.json (DuckGenConfig type)
config.ts # load_duckgen_config() -- reads and validates duck-gen.json
config.libs.ts # INI-style parser helpers (strip_comment, parse_value, unquote, ensure_object_at_path)
core/
paths.ts # Output path resolution, emitFrameworkIndex, emitGeneratedIndex
types.ts # DuckGenOutputPaths, DuckGenOutputTargets
framework/
index.ts # getFrameworkProcessor() dispatcher
nestjs/
index.ts # Barrel re-export
nestjs.ts # processNestJs() -- orchestrates API routes + messages
api-routes/
index.ts # Barrel re-export
api-routes.ts # processNestJsApiRoutes() -- scans @Controller classes
api-routes.emit.ts # emitApiRoutesFile() -- writes the .d.ts output
api-routes.types.ts # Route, HttpMethod, ImportMaps, TypeSymbolImportInfo
api-routes.constants.ts # HTTP_METHOD_DECORATORS, HTTP_METHODS
api-routes.libs.ts # AST helpers for decorators, type text, imports
type-expander.ts # Deep type expansion for response types
messages/
index.ts # Barrel re-export
messages.ts # scanDuckgenMessages() -- finds @duckgen-tagged exports
messages.emit.ts # emitDuckgenMessagesFile() -- writes i18n types
messages.libs.ts # parseDuckgenMessagesTag() -- JSDoc tag parser
messages.types.ts # DuckgenMessageSource
shared/
project.ts # getProject() -- cached ts-morph Project factory
utils.ts # relImport, formatPropKey, sanitizeTypeText, doc, sortMap, isNodeModulesFile
```
## Configuration (duck-gen.json)
The config file lives at the project root. Schema defined in `config.dto.ts` using Zod:
```json
{
"framework": "nestjs",
"extensions": {
"shared": {
"includeNodeModules": false,
"tsconfigPath": "./tsconfig.json",
"sourceGlobs": ["src/**/*.ts"],
"outputSource": "./some/path"
},
"apiRoutes": {
"enabled": true,
"globalPrefix": "/api",
"normalizeAnyToUnknown": true,
"outputSource": "./generated",
"outputPath": "./generated",
"sourceGlobs": ["src/**/*.controller.ts"],
"tsconfigPath": "./tsconfig.json"
},
"messages": {
"enabled": true,
"outputSource": "./generated",
"outputPath": "./generated",
"sourceGlobs": ["src/**/*.messages.ts"],
"tsconfigPath": "./tsconfig.json"
}
}
}
```
Key fields:
- `framework` -- only `"nestjs"` is supported currently
- `extensions.shared.outputSource` -- output directories merged into both apiRoutes and messages output paths
- `extensions.apiRoutes.globalPrefix` -- prepended to all route paths (optional)
- `extensions.apiRoutes.normalizeAnyToUnknown` -- replaces `any` with `unknown` in output
- `outputSource` -- string or string array of extra output directories (per-extension or shared)
- `outputPath` -- fallback for `outputSource` when both are set on apiRoutes or messages; `outputSource` takes precedence
- `tsconfigPath` -- path to tsconfig.json (optional, per-extension or shared)
## API Route Generation
The generator scans NestJS controller files for `@Controller` decorated classes and HTTP method decorators (`@Get`, `@Post`, `@Put`, `@Patch`, `@Delete`, etc.).
For each route method it extracts:
- **Path**: joined from `globalPrefix` + controller prefix + method path
- **HTTP method**: from the decorator name
- **Body/Query/Params/Headers**: from `@Body()`, `@Query()`, `@Param()`, `@Headers()` parameter decorators
- **Response type**: the awaited return type, deeply expanded
The output is a `.d.ts` file with:
```typescript
export interface ApiRoutes {
'/api/auth/signin': RouteMeta<SignInDto, never, never, never, AuthResponse, 'POST'>
'/api/users/:id': RouteMeta<never, never, { id: string }, never, UserResponse, 'GET'>
}
export type RoutePath = keyof ApiRoutes
export type RouteMethod<P extends RoutePath> = RouteOf<P>['method']
export type RouteRes<P extends RoutePath> = RouteOf<P>['res']
export type RouteReq<P extends RoutePath> = CleanupNever<Pick<RouteOf<P>, 'body' | 'query' | 'params' | 'headers'>>
export type DuckFetcher = <P extends RoutePath>(path: P, req: RouteReq<P>) => Promise<RouteRes<P>>
export type RouteMethods = ApiRoutes[RoutePath]['method']
export type RouteOfMethod<P extends keyof ApiRoutes, M extends RouteMethods> = Extract<RouteOf<P>, { method: M }>
export type RouteResMethod<P extends RoutePath, M extends RouteMethods> = RouteOfMethod<P, M>['res']
export type RouteReqMethod<P extends RoutePath, M extends RouteMethods> = CleanupNever<Pick<RouteOfMethod<P, M>, 'body' | 'query' | 'params' | 'headers'>>
export type PathsByMethod<M extends RouteMethods> = { [P in RoutePath]: M extends RouteMethod<P> ? P : never }[RoutePath]
export type DuckClient = { request: DuckFetcher; byMethod: ... }
// plus: GetBody, GetQuery, GetParams, GetHeaders, GetRes, GetReq
```
## Message Generation (i18n)
Tag exported const arrays or objects with `@duckgen` in JSDoc:
```typescript
/** @duckgen messages auth */
export const AUTH_MESSAGES = ['signin.success', 'signin.error', 'signout'] as const
/** @duckgen users */
export const USER_MESSAGES = { 'user.created': true, 'user.deleted': true } as const
```
Supported tag forms:
- `@duckgen` -- uses the const name as group key
- `@duckgen messages` -- same, explicit "messages" keyword
- `@duckgen messages auth` -- uses "auth" as group key
- `@duckgen auth` -- shorthand, uses "auth" as group key
The output `.d.ts` file emits:
```typescript
export type DuckgenMessageSources = {
auth: typeof AUTH_MESSAGES
users: typeof USER_MESSAGES
}
export type DuckgenMessageGroup = keyof DuckgenMessageSources
export type DuckgenMessageKey<G extends DuckgenMessageGroup> = ...
export type DuckgenMessageDictionary<G extends DuckgenMessageGroup> = Record<DuckgenMessageKey<G>, string>
export type DuckGenI18nMessages = DuckgenMessageDictionaryByGroup
export type DuckgenI18n<Lang extends string, G extends DuckgenMessageGroup> = Record<Lang, DuckgenMessageDictionary<G>>
export type DuckgenI18nByGroup<Lang extends string> = Record<Lang, DuckGenI18nMessages>
export type DuckgenScopedI18nByGroup<Lang, ScopeOrMessages, Messages> = ...
```
## @gentleduck/query (Typed Client)
`packages/duck-query/` provides `createDuckQueryClient<Routes>()` which returns a typed Axios wrapper:
```typescript
import { createDuckQueryClient } from '@gentleduck/query'
import type { ApiRoutes } from '@gentleduck/gen/generated'
const api = createDuckQueryClient<ApiRoutes>({ baseURL: 'https://api.example.com' })
// Fully typed -- path, request shape, and response are inferred
// All methods return Promise<AxiosResponse<RouteRes>>
const res = await api.post('/api/auth/signin', { body: { email, password } })
const user = await api.get('/api/users/:id', { params: { id: '123' } })
// Access the underlying Axios instance
api.axios.interceptors.request.use(...)
```
Client properties and methods:
- `axios` -- the underlying `AxiosInstance`
- `request` -- generic fetcher (uses `config.method` or defaults to GET)
- `byMethod` -- explicit method + path fetcher
- `get`, `post`, `put`, `patch`, `del` -- shorthand methods
All methods accept an optional trailing `AxiosRequestConfig` for per-request overrides.
Accepts either an `AxiosInstance` or `AxiosRequestConfig` as the argument to `createDuckQueryClient`.
## CLI Usage
```bash
# Run via npx or bunx (bin name is "duck-gen")
npx duck-gen
bunx duck-gen
```
The CLI reads `duck-gen.json` from cwd, runs the configured extensions, and writes `.d.ts` files to the specified output paths. Uses `ora` for spinners and `chalk` for colored output.
## Import Paths
```typescript
// Generator config types
import type { DuckGenConfig } from '@gentleduck/gen'
// Generated type declarations (after running duck-gen)
import type { ApiRoutes } from '@gentleduck/gen/generated'
import type { ApiRoutes } from '@gentleduck/gen/nestjs'
// JSON schema
import schema from '@gentleduck/gen/schema'
// Typed Axios client
import { createDuckQueryClient } from '@gentleduck/query'
```
## Coding Style
- **Runtime**: Bun (>=1.3.5), ESM (`"type": "module"`)
- **Formatter**: Biome -- single quotes, no semicolons (as-needed), trailing commas, 120 line width, 2-space indent
- **Naming**: snake_case for config/internal functions (`load_duckgen_config`, `config_schema`), camelCase for public API and framework code (`processNestJs`, `emitApiRoutesFile`)
- **Imports**: `node:` protocol for Node builtins, `import type` for type-only imports
- **File naming**: `{feature}.ts` for main, `{feature}.types.ts`, `{feature}.emit.ts`, `{feature}.libs.ts`, `{feature}.constants.ts`
- **Comments**: duck emoji prefix for doc comments (`// 🦆 ...` or `/** 🦆 ... */`)
- **Validation**: Zod schemas for config, ts-morph for AST analysis
- **Build**: tsdown for library builds
- **No semicolons** at end of statements (Biome enforces as-needed)
- **Generated files** start with `// 🦆 THIS FILE IS AUTO-GENERATED. DO NOT EDIT.`
## Do Not
- Do not manually edit files under `generated/` -- they are auto-generated by the CLI
- Do not add framework processors without updating `getFrameworkProcessor()` in `framework/index.ts`
- Do not use `require()` -- the codebase is ESM-only
- Do not skip the Zod validation step when loading config
- Do not import from internal source paths in consumer code -- use the package export map
- Do not add `any` types without `normalizeAnyToUnknown` handling
- Do not create circular imports between `messages/` and `framework/nestjs/api-routes/`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |