Copy page

Extending

Config Layers & Generation

A Zudoku configuration can be composed from multiple layers. This enables a workflow where a tool — for example, the Zuplo portal — emits a serializable spec that zudoku generate turns into a typed base config, while your hand-written zudoku.config.ts stays editable on top.

Extending configurations

Use extends to compose your config from base layers. Like in a tsconfig.json, entries are module specifiers resolved relative to the config file (extension optional):

zudoku.config.ts
import type { ZudokuConfig } from "zudoku";

const config: ZudokuConfig = {
  extends: ["./zudoku.base"],
  site: { title: "My Override" },
};

export default config;

String layers are resolved lazily, when the config is loaded — not when it is written or type-checked. This matters for generated layers: a tool can emit zudoku.base.ts just before zudoku dev or zudoku build runs, and the committed config never needs the file to exist. If a referenced layer is missing at load time, Zudoku fails with a hint to run zudoku generate.

Entries can also be inline config objects (e.g. an imported preset), and both forms can be mixed.

Layers are merged in order, with the config itself applied on top:

• Scalars and nested objects: later layers win, and the top-level config wins over all layers.
• plugins: concatenated in layer order, with the config's own plugins last (never replaced).
• All other arrays (e.g. redirects, navigation): replaced by the later layer.

Layers can themselves use extends; they are resolved depth-first. In dev, layer files are watched like the config file itself, so regenerating a layer reloads the site.

Generating a config layer

zudoku generate turns a serializable spec into a typed config module with real plugin imports:

Code
zudoku generate spec.json -o zudoku.base.ts

The spec is a JSON projection of the Zudoku config where plugins are references into a curated set of plugins instead of code:

spec.json
{
  "$schema": "https://schemas.zudoku.dev/config-spec/v1.json",
  "metadata": { "title": "Acme" },
  "apis": [{ "type": "url", "input": "https://api.acme.dev/openapi.json", "path": "api" }],
  "plugins": [
    {
      "id": "graphql",
      "options": { "type": "url", "input": "https://api.acme.dev/graphql", "path": "graphql" }
    }
  ]
}

The generated output is a normal, typed Zudoku config — it builds and renders like any hand-written config:

zudoku.base.ts
// Generated by `zudoku generate`. Do not edit.
import { graphqlPlugin } from "@zudoku/plugin-graphql";
import type { ZudokuConfig } from "zudoku";

const config: ZudokuConfig = {
  metadata: {
    title: "Acme",
  },
  apis: [
    {
      type: "url",
      input: "https://api.acme.dev/openapi.json",
      path: "api",
    },
  ],
  plugins: [
    graphqlPlugin({
      type: "url",
      input: "https://api.acme.dev/graphql",
      path: "graphql",
    }),
  ],
};

export default config;

A typical setup regenerates the layer right before starting Zudoku and keeps it out of version control:

package.json
{
  "scripts": {
    "generate": "zudoku generate spec.json -o zudoku.base.ts",
    "dev": "pnpm generate && zudoku dev",
    "build": "pnpm generate && zudoku build"
  }
}

Config keys that hold code — slots, mdx, customPages, build, and function options — can't be expressed in a spec. Add them in your zudoku.config.ts on top of the generated layer.

The $schema URL encodes the spec version. Specs with an unknown or unsupported version fail the generator with a clear error, as do unknown plugin ids and invalid plugin options.

The spec's JSON Schema

zudoku schema emits the JSON Schema the spec is validated against, composed from the serializable config keys and the option schemas of all curated plugins:

Code
zudoku schema -o config-spec.json   # or print to stdout: zudoku schema

Use it to validate specs in editors and UIs before running the generator. The same schema is also available programmatically:

Code
import { buildSpecJsonSchema, generateConfig, validateSpec } from "zudoku/codegen";

See the config-spec example for a complete project using a generated layer.