Code Generation Overview

Why Code Generation?

Code generation provides compile-time type safety for your GraphQL queries:

• Catch errors early - TypeScript validates your queries against the schema
• IDE autocomplete - Get suggestions for fields as you type
• Refactoring support - Safely rename fields across your codebase
• No runtime overhead - Types are stripped during compilation

How It Works

UDL's codegen system follows this pipeline:

1. Schema Building - Plugins source data and register GraphQL types
2. Introspection - Codegen introspects the built schema
3. Type Generation - TypeScript interfaces are generated for each type
4. Extension Output - Extensions generate additional code (like typed queries)

Built-in Generation

When you run the UDL server with codegen configured, it automatically generates:

• Type definitions - TypeScript interfaces for all schema types
• Type guards (optional) - Runtime type checking functions

Configuration

Enable codegen in your udl.config.ts:

import { defineConfig } from 'universal-data-layer';

export const config = defineConfig({
  plugins: [
    {
      name: '@universal-data-layer/plugin-source-contentful',
      options: {
        spaceId: process.env['CONTENTFUL_SPACE_ID'],
        accessToken: process.env['CONTENTFUL_ACCESS_TOKEN'],
      },
    },
  ],
  codegen: {
    output: './generated',
  },
});

Output Structure

Generated files are placed in your output directory:

generated/
├── types/
│   └── index.ts     # Type definitions
├── guards/
│   └── index.ts     # Type guards (if enabled)
└── index.ts         # Re-exports everything

Using Generated Types

Import types directly:

import type { ContentfulProduct, ContentfulAsset } from '@/generated';

function displayProduct(product: ContentfulProduct) {
  console.log(product.name);
}

Extensions

Extensions add additional codegen capabilities. The most common is @universal-data-layer/codegen-typed-queries for type-safe query definitions:

import { defineConfig } from 'universal-data-layer';

export const config = defineConfig({
  plugins: ['@universal-data-layer/plugin-source-contentful'],
  codegen: {
    output: './generated',
    extensions: ['@universal-data-layer/codegen-typed-queries'],
  },
});

Codegen Options

Running Codegen

Codegen runs automatically when starting the UDL server. You can also run it standalone:

udl-codegen --endpoint http://localhost:4000/graphql

See the CLI Reference for all options.

Next Steps

• Typed Queries - Generate TypedDocumentNode for full query type safety
• CLI Reference - Standalone codegen CLI options