Contributing

There are two main places to contribute:

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

Before diving in, take a look at the open issues and pull requests, and join the community on Discord.

Prerequisites

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

Kubb core

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

1. Fork and clone

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

2. Install dependencies

pnpm install

3. Create a branch

git checkout -b feat/your-feature-name

4. Iterate

Run a single package in watch mode:

pnpm -F @kubb/core dev

Run the test suite:

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 produces the AST.
packages/parser-ts/	Parser that turns FileNode AST into TypeScript source.
packages/middleware-barrel/	Barrel file middleware.
packages/renderer-jsx/	JSX renderer used by plugins that emit components.
packages/cli/	The kubb CLI entry point.
packages/agent/	Agent server runtime.
packages/mcp/	MCP server runtime.
packages/unplugin-kubb/	Bundler integrations (Vite, webpack, Rollup, 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.

pnpm run typecheck
pnpm run lint
pnpm run test

Kubb plugins

There are two ways to contribute a plugin: build a community plugin in your own repository, or propose a new official plugin in the core monorepo.

Build a community plugin

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

Propose an official plugin

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

Testing

Kubb uses Vitest. Place test files next to the source files they test:

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:

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:

pnpm run changeset

Skip the changeset only for changes that do not affect published code (CI, internal tests, 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.