Architecture
Kubb runs your spec through one pipeline, and you can replace or extend each stage.
You declare the input spec, the output folder, an adapter, and the plugins to run. defineConfig pre-wires the OpenAPI adapter and the default parsers.
| Stage | Job | Output |
|---|---|---|
| Adapter | Reads the spec and resolves its references | An InputNode |
| AST | Describes schemas and operations without naming a spec format or a library | Schema and operation nodes |
| Plugins | Run generators that decide which files and declarations to emit | FileNodes |
| Parsers | Turn each file's nodes into source text | Source code |
| Storage | Writes the files | Files on disk or in memory |
From one operation to generated files
Take GET /pet/{petId} (getPetById), whose response refers to a Pet schema:
- The adapter resolves the
$refinto an operation node and aPetschema node. plugin-tsemits thePetandGetPetByIdtypes, andplugin-axiosemits agetPetByIdfunction that imports them.- A parser prints each file, and storage writes it.
Generate your first client builds this example.
Adapters
An adapter handles everything specific to the input format: references, nullability, discriminators, and formats. The default is the OpenAPI adapter. A custom adapter converts another format into the same AST, so every plugin works with it.
AST
The AST is the model the adapter and the plugins share, so no plugin resolves references itself. An InputNode holds the reusable schemas and the operations, and operations link parameters, request bodies, and responses to schema nodes.
Every node has a kind, and schema nodes also have a type. See AST and node builders.
Plugins
Each plugin owns one output, such as types, a client, or your own files. defineExtension({ kind: 'plugin' }) returns the factory you call in kubb.config.ts. Its setup runs once and registers generators, a resolver, and macros.
Generators
A generator turns AST nodes into files.
| Handler | Kubb calls it |
|---|---|
schema | Once per schema node |
operation | Once per operation node |
operations | Once per plugin, with every operation node its filters keep |
A handler returns FileNodes or elements for a renderer. See Generators.
Resolvers
A resolver decides identifiers, file names, and paths. A plugin that builds on another reads its resolver, so the Axios client still imports the right names after you rename the types. See Resolvers.
Macros and printers
A macro rewrites AST nodes before the generators see them, per plugin, so a change reaches every generator of that plugin and no other. A printer turns a schema node into code for one target, such as a TypeScript type or a Zod expression. See Macros and Printers.
Renderers
A renderer turns the elements a generator returns into FileNodes. jsxRenderer from kubb/jsx renders JSX without React. Set it per generator with renderer. See JSX renderer.
Lifecycle
- The adapter parses the spec.
- Each plugin's
setupandkubb:plugin:setuprun once, in plugin order. - Kubb walks the AST once, schemas first. Each node goes to every plugin, through its macros and
include,exclude, andoverridefilters. - Each plugin's
operationshandler runs, thenkubb:plugin:endfires. - After
kubb:plugins:end, Kubb writes all files through the parsers and storage. - Format, lint, and
postGeneraterun when the config sets them.
Lifecycle hooks lists every hook.
Dependencies and ordering
Kubb orders the plugins before setup:
Dependencies win over enforce, and ties keep their order in plugins. With plugins: [pluginAxios(), pluginTs()], plugin-ts comes first because plugin-axios depends on it. plugin-barrel, which defineConfig adds, sets enforce: 'post', so it runs last and sees every file the others emitted.
Parsers
Kubb sends each FileNode to the parser that claims its extension. Without a parsers option, defineConfig adds parserTs (.ts, .js), parserTsx (.tsx, .jsx), and parserMd (.md, .markdown). The TypeScript parser prints a file's banner, imports, and source nodes:
To write one, see Parsers.
Storage
Storage decides where files go, so the same build writes to disk from the CLI or to memory in a test. Kubb skips files whose content has not changed.
| Driver | Writes to |
|---|---|
fsStorage() | Disk. The default. |
memoryStorage() | A Map in memory |
| Your own | Any backend that implements the Storage interface |
Choose an extension
If an existing plugin generates the output you need, use it. Otherwise, build on kubb/kit, which ships with kubb.
| Extension | Example | Start with |
|---|---|---|
| Adapter | Read a format other than OpenAPI | Adapters |
| Plugin | Generate a new kind of file | Create a plugin |
| Macro | Treat every integer as a string in one plugin | Macros |
| Printer | Print date schemas as the TypeScript Date type | Printers |
| Resolver | Move model files into a folder | Resolvers |
| Parser | Emit a new file type | Parsers |
| Storage | Write to a remote store | Storage |
