Codegen
CLI Reference
Command-line interface for UDL code generation
Overview
The udl-codegen CLI generates TypeScript types from various sources. Use it standalone or let it run automatically when starting the UDL server.
Usage
Terminal
udl-codegen [options]
Source Options
| Option | Short | Description |
|---|---|---|
--endpoint <url> | -e | GraphQL endpoint to introspect |
--from-response <file> | -r | JSON file to infer types from |
--type <name> | -t | Type name for response inference (required with -r) |
--from-store | -s | Infer from UDL node store (requires running server) |
Output Options
| Option | Short | Default | Description |
|---|---|---|---|
--output <path> | -o | ./generated | Output directory |
--guards | -g | false | Generate type guard functions |
Behavior Options
| Option | Short | Description |
|---|---|---|
--watch | -w | Watch for changes and regenerate |
--clean | -c | Remove generated files |
--dry-run | -d | Preview without writing files |
Config Options
| Option | Short | Default | Description |
|---|---|---|---|
--config <file> | -C | udl.config.ts | Path to config file |
Generator Options
| Option | Default | Description |
|---|---|---|
--no-internal | false | Exclude internal metadata fields |
--no-jsdoc | false | Exclude JSDoc comments |
--export-type | false | Use type instead of interface |
Other Options
| Option | Short | Description |
|---|---|---|
--help | -h | Show help message |
--version | -v | Show version number |
Examples
Generate from GraphQL Endpoint
The most common usage - introspect a running UDL server:
Terminal
# Start your UDL server first
npx universal-data-layer &
# Then generate types
udl-codegen --endpoint http://localhost:4000/graphql
Generate with Type Guards
Include runtime type checking functions:
Terminal
udl-codegen -e http://localhost:4000/graphql --guards
Generated guards look like:
export function isContentfulProduct(value: unknown): value is ContentfulProduct {
// Runtime type checking
}
Generate from JSON Response
Useful for mocking or quick prototyping:
Terminal
udl-codegen --from-response ./samples/product.json --type Product
This infers a TypeScript interface from the JSON structure.
Watch Mode
Automatically regenerate when schemas change:
Terminal
udl-codegen -e http://localhost:4000/graphql --watch
With --endpoint, watch mode polls every 5 seconds for schema changes.
Preview Changes
See what would be generated without writing files:
Terminal
udl-codegen -e http://localhost:4000/graphql --dry-run
Clean Generated Files
Remove all generated files:
Terminal
udl-codegen --clean
Custom Output Directory
Terminal
udl-codegen -e http://localhost:4000/graphql --output ./src/types
Using with Config File
If you have a udl.config.ts with codegen settings, CLI options override config file values:
Terminal
# Uses settings from udl.config.ts but overrides output
udl-codegen --output ./custom-types
Integration with Package Scripts
Add to your package.json:
package.json
{
"scripts": {
"codegen": "udl-codegen -e http://localhost:4000/graphql",
"codegen:watch": "udl-codegen -e http://localhost:4000/graphql --watch",
"codegen:clean": "udl-codegen --clean"
}
}
Then run:
Terminal
npm run codegen
Exit Codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Error (missing source, invalid options, generation failure) |
Next Steps
- Code Generation Overview - Configure codegen in your project
- Typed Queries - Generate TypedDocumentNode for queries