Reference

Configuration Reference

Complete reference for UDL configuration options

Configuration File

UDL looks for configuration files in this order:

udl.config.ts (recommended)
udl.config.js
udl.config.mjs
udl.config.cjs

defineConfig Helper

Use defineConfig for TypeScript support and autocomplete:

udl.config.ts

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

export const config = defineConfig({
  // Your configuration
});

UDLConfig Interface

The main configuration object:

interface UDLConfig {
  // Plugin metadata (for plugin configs)
  type?: 'source' | 'core' | 'other';
  name?: string;
  version?: string;

  // Server configuration
  port?: number;
  host?: string;
  endpoint?: string;
  staticPath?: string;

  // Plugins
  plugins?: PluginSpec[];
  indexes?: string[];

  // Code generation
  codegen?: CodegenConfig;

  // Caching
  cache?: CacheStorage | false;
}

Server Options

Option	Type	Default	Description
`port`	`number`	`4000`	Server port
`host`	`string`	`'localhost'`	Server host
`endpoint`	`string`	`'/graphql'`	GraphQL endpoint path
`staticPath`	`string`	`'/static/'`	Static files path

udl.config.ts

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

export const config = defineConfig({
  port: 3001,
  host: '0.0.0.0',
  endpoint: '/api/graphql',
});

Plugin Metadata

For plugin configurations:

Option	Type	Description
`type`	`'source' \| 'core' \| 'other'`	Plugin type
`name`	`string`	Plugin name
`version`	`string`	Plugin version
`indexes`	`string[]`	Default indexed fields

Plugin Configuration

PluginSpec

Plugins can be specified as strings or objects:

type PluginSpec = string | {
  name: string;
  options?: Record<string, unknown> & {
    indexes?: string[];
  };
};

Registration Methods

udl.config.ts

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

export const config = defineConfig({
  plugins: [
    // String shorthand (no options)
    'my-simple-plugin',

    // Object with options
    {
      name: '@universal-data-layer/plugin-source-contentful',
      options: {
        spaceId: process.env['CONTENTFUL_SPACE_ID'],
        accessToken: process.env['CONTENTFUL_ACCESS_TOKEN'],
        environment: 'master',
        indexes: ['slug'],
      },
    },

    // Local plugin path
    './plugins/my-local-plugin',
  ],
});

Plugin Options

Each plugin defines its own options. Common patterns:

{
  name: '@universal-data-layer/plugin-source-contentful',
  options: {
    // Plugin-specific options
    spaceId: 'xxx',
    accessToken: 'yyy',

    // UDL-recognized option: fields to index for O(1) lookups
    indexes: ['slug', 'contentfulId'],
  },
}

Codegen Configuration

CodegenConfig Interface

interface CodegenConfig {
  output?: string;
  guards?: boolean;
  includeJsDoc?: boolean;
  includeInternal?: boolean;
  types?: string[];
  extensions?: (CodegenExtension | string)[];
}

Options

Option	Type	Default	Description
`output`	`string`	`'./generated'`	Output directory
`guards`	`boolean`	`false`	Generate type guard functions
`includeJsDoc`	`boolean`	`true`	Include JSDoc comments
`includeInternal`	`boolean`	`true`	Include `internal` metadata field
`types`	`string[]`	all types	Specific types to generate
`extensions`	`string[]`	`[]`	Codegen extensions to run

Example

udl.config.ts

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

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

Cache Configuration

Control node caching behavior:

Value	Behavior
`undefined` (default)	File-based cache in `.udl/cache/nodes.json`
`false`	Disable caching entirely
`CacheStorage`	Custom cache implementation

udl.config.ts

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

export const config = defineConfig({
  // Disable caching
  cache: false,
});

Environment Variables

Common pattern for sensitive data:

.env

CONTENTFUL_SPACE_ID=your_space_id
CONTENTFUL_ACCESS_TOKEN=your_token
CONTENTFUL_ENVIRONMENT=master

udl.config.ts

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

export const config = defineConfig({
  port: parseInt(process.env['PORT'] || '4000', 10),
  plugins: [
    {
      name: '@universal-data-layer/plugin-source-contentful',
      options: {
        spaceId: process.env['CONTENTFUL_SPACE_ID'],
        accessToken: process.env['CONTENTFUL_ACCESS_TOKEN'],
        environment: process.env['CONTENTFUL_ENVIRONMENT'] || 'master',
      },
    },
  ],
});

Complete Example

udl.config.ts

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

const isDev = process.env['NODE_ENV'] === 'development';

export const config = defineConfig({
  // Server
  port: isDev ? 4000 : 3000,
  host: isDev ? 'localhost' : '0.0.0.0',

  // Plugins
  plugins: [
    {
      name: '@universal-data-layer/plugin-source-contentful',
      options: {
        spaceId: process.env['CONTENTFUL_SPACE_ID'],
        accessToken: isDev
          ? process.env['CONTENTFUL_PREVIEW_TOKEN']
          : process.env['CONTENTFUL_ACCESS_TOKEN'],
        host: isDev ? 'preview.contentful.com' : 'cdn.contentful.com',
        environment: process.env['CONTENTFUL_ENVIRONMENT'] || 'master',
        indexes: ['slug', 'contentfulId'],
      },
    },
    // Dev-only plugin
    ...(isDev ? ['./plugins/dev-logger'] : []),
  ],

  // Code generation
  codegen: {
    output: './generated',
    guards: true,
    extensions: ['@universal-data-layer/codegen-typed-queries'],
  },
});

Next Steps

Plugin Overview - How to use plugins
Creating Plugins - Build custom plugins
Production Deployment - Deploy UDL for production

Edit this pageorReport an issue

Lifecycle Methods

Understanding plugin lifecycle hooks in Universal Data Layer

Contributing

Help improve Universal Data Layer