Contributing

There are two places to contribute:

1. Kubb core: the runtime, AST, adapter, parsers, and built-in plugins in kubb-labs/kubb.
2. Kubb plugins: community and official plugins in the registry at kubb-labs/plugins.

First, check the open issues and pull requests so you don't duplicate work. Say hello on Discord.

Prerequisites

• Node.js 22 or later.
• pnpm 11 or later.
• Git and, optionally, the GitHub CLI.

Kubb core

The monorepo at kubb-labs/kubb holds everything in the kubb and @kubb/* packages.

1. Fork and clone

Terminal

gh repo fork kubb-labs/kubb --clone
cd kubb

2. Install dependencies

Terminal

pnpm install

3. Create a branch

Terminal

git checkout -b feat/your-feature-name

4. Iterate

Run a single package in watch mode:

Terminal

pnpm -F @kubb/core dev

Run the test suite:

Terminal

pnpm run test

What lives where

Path	What lives there
packages/core/	Plugin runtime, build loop, definePlugin/createKubb API.
packages/ast/	Universal AST and visitor utilities.
packages/adapter-oas/	OpenAPI adapter that parses an OAS 2.0/3.x spec into the AST.
packages/parser-ts/	Parser that turns the AST into TypeScript and TSX source.
packages/parser-md/	Parser that turns the AST into Markdown source.
packages/plugin-barrel/	Barrel file plugin (enforce: 'post').
packages/renderer-jsx/	JSX renderer used by plugins that emit components.
packages/cli/	The kubb CLI entry point.
packages/mcp/	MCP server runtime.
packages/unplugin-kubb/	Bundler integrations (Vite, webpack, Rollup, Rspack, esbuild, Nuxt, Astro).
packages/kubb/	The meta package that re-exports defineConfig with sensible defaults.

Quality gates

Run these locally before pushing. CI runs the same commands.

Terminal

pnpm run typecheck
pnpm run lint
pnpm run test

Kubb plugins

Contribute a plugin in two ways. Build a community plugin in your own repository, or propose an official one in the core monorepo.

Build a community plugin

1. Follow the Creating Your First Plugin guide.
2. Use @kubb/plugin-axios as the layout to copy.
3. Publish to npm under the kubb-plugin-* or @scope/plugin-* naming convention.
4. Submit it to the community registry. Add a YAML entry under plugins/.

Propose an official plugin

Official plugins ship under @kubb/plugin-*. First, open an issue on the kubb-labs/plugins repo to discuss scope and naming. Once approved, scaffold the package under packages/plugin-<name>/. Follow the structure of an existing plugin.

Testing

Kubb uses Vitest. Place each test file next to the source file it tests.

resolverExample.test.ts

import { describe, expect, it } from 'vitest'
import { resolverExample } from './resolverExample.ts'

describe('resolverExample', () => {
  it('returns a default resolver name', () => {
    const resolver = resolverExample({})
    expect(resolver.name).toBe('default')
  })
})

Run tests for a single package:

Terminal

pnpm -F @kubb/core test

Commits and changesets

Follow Conventional Commits: feat:, fix:, docs:, chore:.

Add a changeset for any change that ships in a published package:

Terminal

pnpm run changeset

Skip the changeset only when the change does not affect published code, such as CI, internal tests, or docs.

Opening a pull request

1. Push your branch to your fork.
2. Open a pull request against main.
3. Fill in the PR template and link the related issue.
4. Make sure CI is green and re-request review after each round of changes.

Getting help

Open an issue or join the Discord.