Kubb Documentation

The Kubb Claude Code plugin extends Claude's capabilities for code generation using the Kubb meta-framework. It includes several specialized intelligence layers:

• config skill: Teaches Claude how to write kubb.config.ts and select appropriate @kubb/plugin-* packages.
• output skill: Teaches Claude how to import and utilize the generated artifacts (types, clients, hooks, schemas, and mocks).
• kubb-expert agent: An agent capable of handling end-to-end tasks, such as "add Kubb to my project," from the initial specification to the final generated code.
• Kubb MCP server integration: Wires in the Kubb MCP server (kubb mcp) to allow for conversational code generation via chat rather than just CLI commands.

The @kubb/core package is the core engine for Kubb's plugin-based code generation system. It provides the fundamental building blocks used by every Kubb plugin, including:

• The plugin driver
• The file manager
• defineConfig for configuration
• definePlugin for plugin definition
• defineMiddleware for middleware definition
• The build orchestration layer

The @kubb/ast package provides a spec-agnostic Abstract Syntax Tree (AST) layer used by all Kubb code generation plugins. It defines the node tree, visitor patterns, factory functions, and type guards.

Important Integration Note: While the examples below use direct imports from @kubb/ast, most Kubb plugins and generators should access the AST via the ast namespace provided by kubb/kit. This allows plugins to interact with the AST without a direct dependency on the @kubb/ast package. For example, ast.factory.createSchema is the standard way to access constructors when using kubb/kit.

The plugin operates as a post-generation step. After every other plugin finishes generating files, @kubb/plugin-barrel walks the output tree and:

1. Creates an index.ts in each directory, re-exporting everything inside.
2. Creates a root index.ts at the top of the output path that re-exports from all plugin directories.

It uses enforce: 'post' to ensure it always runs after all regular plugins have completed, allowing it to access the full set of generated files.

The type option determines how the generated index.ts files re-export content:

• 'all': Uses wildcard re-exports (export * from './...').
• 'named': Uses named re-exports (export { ... } from './...'). This is the default and is tree-shaking friendly.
• 'propagate': Uses wildcard re-exports (export * from './...') on index files only, propagating up through directories.

Because export names (derived from operationId and schema names) and casing/grouping are configurable, you should not assume exact names. Use these methods to find the correct identifiers:

1. Inspect the filesystem: List the contents of your output.path to see the actual file and export names.
2. Check Plugin Options: To understand how a plugin behaves or what its defaults are, inspect the plugin's Options type. You can find this in:
   • node_modules/@kubb/plugin-<name>/src/types.ts
   • The published type declarations in your IDE.
3. Consult Documentation: Visit https://kubb.dev/plugins/plugin-<name> for the official documentation and dependency requirements for a specific plugin.

The unplugin-kubb package provides specific entry points for different build tools and frameworks. Import the corresponding entry point to add Kubb to your configuration.

// Vite
import kubb from 'unplugin-kubb/vite'
export default defineConfig({
  plugins: [kubb({/* options */})],
})

// Rollup
import kubb from 'unplugin-kubb/rollup'
export default {
  plugins: [kubb({/* options */})],
}

// Webpack
module.exports = {
  /* ... */
  plugins: [require('unplugin-kubb/webpack')({/* options */})],
}

// Nuxt
export default defineNuxtConfig({
  modules: [['unplugin-kubb/nuxt', {/* options */}]],
})

// esbuild
import { build } from 'esbuild'
import kubb from 'unplugin-kubb/esbuild'
build({
  plugins: [kubb()],
})

Install the @kubb/renderer-jsx package using your preferred package manager to enable JSX-based code generation in your Kubb plugins.

bun add @kubb/renderer-jsx
# or
pnpm add @kubb/renderer-jsx
# or
npm install @kubb/renderer-jsx