Contributing
Check the open issues and pull requests first. Open an issue before an opinion-driven change. Each repository's CONTRIBUTING.md has the full rules: kubb-labs/kubb and kubb-labs/plugins.
What lives where
| Repository | Holds |
|---|---|
| kubb-labs/kubb | The kubb and @kubb/* core packages, and these docs in docs/ |
| kubb-labs/plugins | The official @kubb/plugin-* packages, with a runnable example per plugin |
| kubb-labs/platform | The kubb.dev site, its blog, and Kubb Studio |
Kubb core
| Path | Holds |
|---|---|
packages/core/ | Plugin runtime, build loop, defineExtension, createKubb |
packages/kit/ | Authoring toolkit behind kubb/kit |
packages/ast/ | Universal AST and visitors |
packages/adapter-oas/ | OpenAPI 2.0 and 3.x adapter |
packages/parser-ts/, parser-md/ | AST to TypeScript, TSX, and Markdown source |
packages/plugin-barrel/ | Barrel file plugin |
packages/renderer-jsx/ | JSX renderer |
packages/cli/ | The kubb CLI |
packages/mcp/ | MCP server |
packages/studio/ | The Studio connection behind kubb studio |
packages/unplugin-kubb/ | Build tool integrations |
packages/kubb/ | The main package: public APIs and defineConfig |
Workflow
Both repositories need Node.js 22.22 or later, pnpm 11 or later, and Git. Run corepack enable to get the pnpm version the repository pins.
Fork and clone
gh repo fork kubb-labs/kubb --clone
cd kubbgh repo fork kubb-labs/plugins --clone
cd pluginsInstall dependencies
pnpm install
pnpm buildpnpm build compiles every package so local packages resolve each other. Rerun it after you change package source.
Create a branch
git checkout -b feat/your-feature-nameIterate
pnpm -F @kubb/core start # rebuild one package on change
pnpm vitest run --config ./configs/vitest.config.ts packages/core # test one packagePut each test next to its source file. List a new test file in configs/test-registry.json, with one sentence on what it covers. In kubb-labs/plugins, test a folder such as packages/plugin-ts, and run pnpm generate after a plugin change.
Add a changeset
Run pnpm changeset when the change ships in a published package, including a package's docs/ folder, because kubb.dev reads it from the published version. Changes to docs/5.x, CI, and tests need none. Write Conventional Commits, such as feat: or fix:.
Open a pull request
Push to your fork and open a pull request against main. Fill in the template, link the issue, and re-request review after each round of changes.
Quality gates
Run these before you push. CI runs them on every pull request that changes code.
| Command | Checks | CI job |
|---|---|---|
pnpm build | Every package builds | Build |
pnpm typecheck | Types in every package | Typecheck |
pnpm test | The Vitest suites | Tests |
pnpm lint | oxlint rules | Linting |
pnpm test:registry | Every test file has a registry entry, and no entry points at a deleted file | Linting |
pnpm format | oxfmt formatting | autofix.ci formats the pull request |
pnpm typecheck:examples | Plugins only: the examples type-check | Typecheck |
pnpm generate | Plugins only: generates the examples | Update generated examples, which opens a pull request with the changes |
Write a plugin
| Kind | Where | How |
|---|---|---|
| Community plugin | Your own repository, on npm under a name you own | Create a Kubb plugin, then Publish a plugin. Copy the layout of plugin-axios. |
| Official plugin | packages/plugin-<name>/ in kubb-labs/plugins, as @kubb/plugin-<name> | Open an issue to agree on scope and name, then follow Adding a plugin. |
