Open Studio
Community

Contributing

A concise guide to contributing to Kubb core and Kubb plugins.

There are two places to contribute:

  1. Kubb core: the runtime, AST, adapter, parsers, the authoring kit, 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 ​

Kubb core ​

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

1. Fork and clone ​

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

2. Install dependencies ​

Terminal
shell
pnpm install

3. Create a branch ​

Terminal
shell
git checkout -b feat/your-feature-name

4. Iterate ​

Run a single package in watch mode:

Terminal
shell
pnpm -F @kubb/core start

Run the test suite:

Terminal
shell
pnpm run test

What lives where ​

PathWhat lives there
packages/core/Plugin runtime, build loop, definePlugin/createKubb API.
packages/kit/Authoring toolkit re-exported through kubb/kit, holding definePlugin, defineGenerator, createAdapter, createRenderer, and the ast node builders.
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
shell
pnpm run typecheck
pnpm run lint
pnpm run test

Kubb plugins ​

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-* naming convention.
  4. Submit it to the registry by opening a PR on kubb-labs/docs that adds a plugins/<id>/index.md page with the required frontmatter.

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
typescript
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
shell
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
shell
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.

Diagnostics

FAQ