4. Each package has its own tsdown.config.ts; run tsdown --config packages/core/tsdown.config.ts to build individual packages, or wire them all through your monorepo build script.
5. For the agent server, run nitro build inside packages/agent/ and start with node .output/server/index.mjs.

Public API

parseDocument

import { parseDocument } from '@kubb/adapter-oas'

async function parseDocument(
  source: string | Document,
  options?: ParseOptions
): Promise<Document>

Parses a raw OpenAPI YAML/JSON string or URL into a validated Document object. Use this as the first step in any generation pipeline before handing the document off to the plugin driver.

createKubb

import { createKubb } from '@kubb/core'

function createKubb(options: KubbConfig): Kubb

Instantiates the main Kubb orchestrator, wiring together plugins, the file manager, and the plugin driver. This is the central entry point for programmatic generation; call .build() on the returned instance to run the full pipeline.

definePlugin

import { definePlugin } from '@kubb/core'

function definePlugin<TOptions>(factory: (options: TOptions) => Plugin): PluginFactory<TOptions>

Creates a typed plugin factory. Plugins define hooks (buildStart, buildEnd, generateFiles, etc.) and are consumed by createKubb. Use this whenever you want to extend the generation pipeline with custom output logic.

createSchema

import { createSchema } from '@kubb/ast'

function createSchema(options: SchemaOptions): SchemaNode

Constructs a typed SchemaNode in the Kubb AST. Use this inside a plugin's file-generation step to represent an OpenAPI schema as an AST node that printers can later render to TypeScript, Zod, etc.

walk

import { walk } from '@kubb/ast'

function walk(node: Node, visitor: Visitor): void

Traverses an AST tree depth-first, calling visitor hooks on each node. Use this when you need to inspect or transform all schema nodes of a specific kind (e.g. collect all enum nodes before rendering).

Working examples

Scenario - Parse and validate an OpenAPI document

Load a local OpenAPI file and confirm it is valid before passing it downstream.

import { readFileSync } from 'node:fs'
import { parseDocument, validateDocument } from '@kubb/adapter-oas'

const raw = readFileSync('./openapi.yaml', 'utf-8')

const doc = await parseDocument(raw)
const result = await validateDocument(doc, { strict: true })

if (result.errors.length) {
  console.error('OpenAPI validation errors:', result.errors)
  process.exit(1)
}

console.log('Operations found:', Object.keys(doc.paths ?? {}).length)

Scenario - Run programmatic code generation with a custom plugin

Define a minimal plugin that logs every generated file path.

import { createKubb, definePlugin } from '@kubb/core'
import { adapterOas } from '@kubb/adapter-oas'

const loggerPlugin = definePlugin<{ prefix: string }>((options) => ({
  name: 'logger-plugin',
  async buildEnd({ files }) {
    for (const file of files) {
      console.log(`${options.prefix}: ${file.path}`)
    }
  },
}))

const kubb = createKubb({
  input: { path: './openapi.yaml' },
  output: { path: './src/generated' },
  plugins: [
    adapterOas({}),
    loggerPlugin({ prefix: '[generated]' }),
  ],
})

await kubb.build()

Scenario - Build and walk a schema AST node

Construct an object schema with two properties and visit each property node.

import { createSchema, createProperty } from '@kubb/ast'
import { walk } from '@kubb/ast'
import type { SchemaNode, PropertyNode } from '@kubb/ast'

const schema: SchemaNode = createSchema({
  type: 'object',
  properties: [
    createProperty({ name: 'id', schema: createSchema({ type: 'number' }) }),
    createProperty({ name: 'name', schema: createSchema({ type: 'string' }) }),
  ],
})

walk(schema, {
  Property(node: PropertyNode) {
    console.log('property:', node.name)
  },
})

Scenario - Use the CLI programmatically

Invoke the Kubb CLI runner from a Node.js script without spawning a child process.

import { run } from '@kubb/cli'

await run(['node', 'kubb', 'generate', '--config', './kubb.config.ts'])

File walkthrough

• adapter-oas/ - Contains adapterOas plugin factory, parseDocument, validateDocument, mergeDocuments, and all OpenAPI type exports (Operation, SchemaObject, HttpMethods, etc.).
• agent/ - Nitro server that exposes REST and WebSocket endpoints for remote generation; houses route handlers, plugin loaders, config resolvers, and WebSocket publish utilities.
• ast/ - Core AST layer: factory.ts has all create* functions, visitor.ts has walk/collect/transform, transformers.ts has schema mutation helpers, nodes/ contains all TypeScript node type definitions.
• cli/ - Exports a single run(argv) function that registers generate, validate, mcp, agent, and init commands and dispatches to them.
• core/ - The orchestration layer: createKubb, definePlugin, defineGenerator, FileManager, PluginDriver, FileProcessor, storage adapters (fsStorage, memoryStorage), and all shared types.
• kubb/ - Thin re-export meta-package bundling core and adapter surfaces for consumers who want a single install.
• mcp/ - MCP server for AI tool integrations; exposes generation capabilities over the Model Context Protocol.
• parser-ts/ - Utilities for parsing TypeScript source files, used by renderers and plugins that analyze existing code.
• renderer-jsx/ - JSX printer adapter; turns AST nodes into TypeScript/JSX source strings.
• unplugin-kubb/ - Wraps createKubb in an unplugin so Kubb generation runs inside Vite, Rollup, or webpack build pipelines.

Common pitfalls and fixes

• ESM/CJS mismatch: Kubb packages publish as ESM. If your project uses "type": "commonjs" you must use dynamic import() or switch to "type": "module". Fix: add "type": "module" to your package.json.
• moduleResolution must be bundler or node16: Imports use .ts extensions. Fix: set "moduleResolution": "bundler" in tsconfig.json.
• Missing oas peer dependency: adapter-oas does not bundle oas. Fix: npm install oas.
• Telemetry noise in CI: The CLI prints a telemetry notice on TTY. Fix: set KUBB_DISABLE_TELEMETRY=1 in your CI environment.
• createKubb called before document is reachable: If input.path is a URL that requires auth, the default fetch will fail silently. Fix: use parseDocument manually and pass the resulting Document object as input.data.
• Plugin order matters: adapterOas must appear before any generator plugin in the plugins array because generator plugins depend on the parsed document being present in the context. Fix: always list adapterOas({}) first.

Vibe-coding prompt template

I have a copy of the Kubb plugin packages in `source/` and a usage guide in `USAGE.md`.
The upstream npm package is `@kubb/root@0.0.0` (monorepo: core, AST, CLI, adapter-oas, etc.).

Please help me integrate Kubb into my existing TypeScript project step by step:

1. Read USAGE.md and the file excerpts I have provided.
2. Install the required dependencies listed in the "Required dependencies" section.
3. Update my tsconfig.json with the path aliases from the "Project setup" section.
4. Create a `kubb.config.ts` at the project root that uses `createKubb` from `source/core/src/index.ts`
   and `adapterOas` from `source/adapter-oas/src/index.ts`, pointing to my OpenAPI file at `./openapi.yaml`
   and outputting to `./src/generated`.
5. Add a `generate` npm script that calls the CLI `run()` from `source/cli/src/index.ts`.
6. If I need a custom plugin, scaffold one using `definePlugin` from `source/core/src/index.ts`.

Only use symbols that appear in USAGE.md or in the source index files. Do not invent APIs.
Ask me for clarification if my project structure requires deviating from the setup steps.

License and credit

See source/LICENSE if present in the upstream repository, or refer to the license field in each package's package.json. Upstream source: @kubb/root by Kubb Labs. All credit for the original implementation belongs to the Kubb Labs contributors.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Orval OpenAPI TypeScript Client Code Generator

Automation, Utilities & Developer Tools

Free