Copy page

Extending

Build Configuration

The zudoku.build.ts file allows you to configure build-time settings and processors for your Dev Portal project. This file is executed during the build process and can be used to transform your API schemas before they are used in the documentation.

File Location

Create a file named zudoku.build.ts in the root of your project:

Code
your-project/
├── zudoku.config.ts
├── zudoku.build.ts    # <-- Add this file
└── ...

Basic Configuration

Here's a basic example of a build configuration file:

Code
import type { ZudokuBuildConfig } from "zudoku";

const buildConfig: ZudokuBuildConfig = {
  processors: [
    async ({ schema }) => {
      // Transform your schema here
      return schema;
    },
  ],
  remarkPlugins: [],
  rehypePlugins: [],
};

export default buildConfig;

Configuration Options

processors

An array of functions that transform your API schemas. Each processor receives:

• file: The path to the schema file
• schema: The OpenAPI schema object
• params: Query parameters extracted from the input string (see Splitting Schemas)
• dereference: A function to dereference the schema

Processors are executed in order, and each processor receives the output of the previous one.

Here's a simple example that adds a description to all operations:

Code
async function addDescriptionProcessor({ schema }) {
  if (!schema.paths) return schema;

  // Add a description to all operations
  Object.values(schema.paths).forEach((path) => {
    Object.values(path).forEach((operation) => {
      if (typeof operation === "object" && operation) {
        operation.description = "This is a public API endpoint";
      }
    });
  });

  return schema;
}

export default {
  processors: [addDescriptionProcessor],
};

remarkPlugins

An array of Remark plugins to transform Markdown content. These plugins run before the content is converted to HTML.

Code
import remarkContributors from "remark-contributors";

export default {
  remarkPlugins: [remarkContributors],
};

rehypePlugins

An array of Rehype plugins to transform HTML content. These plugins run after Markdown is converted to HTML.

Code
import rehypeKatex from "rehype-katex";

export default {
  rehypePlugins: [rehypeKatex],
};

prerender

Configuration for the prerendering process that generates static HTML pages during build time.

• workers: Number of parallel workers to use for prerendering. Defaults to 80% of available CPU cores.

Code
import os from "node:os";

export default {
  prerender: {
    workers: 4, // Fixed number of workers
  },
};

// Or use a percentage of available CPU cores
export default {
  prerender: {
    workers: Math.floor(os.cpus().length * 0.75), // Use 75% of available cores
  },
};