Skip to content
How-to guides

Publish a plugin

Package a Kubb plugin with a kubb-extension.json manifest and docs, publish it to npm or a GitHub release, and submit it to the Kubb registry.

Once your plugin is in the Kubb registry, users install it with kubb add and find it on kubb.dev/extensions and in Kubb Studio. You package it, publish it, and submit it. Adapters and parsers follow the same steps. Start from a working plugin with a test, such as the one from Create a plugin.

A package already on npm still needs the manifest and the docs/ folder in a published version. Add them, publish a new version, then go to Submit to the registry.

Build the package

Export the factory from the package entry point. Give relative imports a .js extension so the compiled ESM works in Node:

src/index.ts
export { pluginExample } from './plugin.js'

Add a TypeScript build config and these package.json fields. Replace the package name with an available name you own:

package.json
{
  "name": "kubb-plugin-example",
  "version": "1.0.0",
  "type": "module",
  "files": ["dist", "kubb-extension.json", "docs"],
  "repository": { "type": "git", "url": "https://github.com/acme/kubb-plugin-example" },
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "test": "vitest run src/plugin.test.ts",
    "prepack": "npm run build && npm test"
  },
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    },
    "./kubb-extension.json": "./kubb-extension.json",
    "./package.json": "./package.json"
  },
  "peerDependencies": { "kubb": "^5.0.0" }
}

Before you publish, check that:

  • files ships the build, the manifest, and the docs/ folder.
  • exports lists kubb-extension.json and package.json, because an exports map hides every path it does not list.
  • repository points to a GitHub repository you own, or one in an organization you belong to.
  • kubb or @kubb/core is a peer dependency, not a bundled one. Keep kubb as a dev dependency too, to build and test locally.
  • A preinstall, install, or postinstall script is allowed only when the overview explains what it does.

Add the manifest

Create kubb-extension.json at the package root. It tells the registry, kubb add, and Studio what the package is and which factory to call:

kubb-extension.json
{
  "$schema": "https://kubb.dev/schemas/kubb-extension.json",
  "kind": "plugin",
  "name": "plugin-example",
  "export": "pluginExample",
  "displayName": "Example",
  "description": "Writes a comment with the HTTP method and path of every operation.",
  "maintainers": [{ "name": "Acme", "github": "acme" }],
  "compatibility": { "kubb": ">=5.8.3", "node": ">=22" }
}
  • Set name to the plugin's meta.name and export to the factory that src/index.ts exports.
  • Give meta.compatibility in src/plugin.ts the same ranges, so Kubb checks them at runtime too. With a bundler, import compatibility from the manifest.

Extension manifest lists every field and the options Studio shows as a form.

Write the docs

Create a docs/ folder next to the manifest. kubb.dev renders it as the extension's page:

docs/
docs/
├── overview.md        required
├── options.md         optional, the full option reference
└── guides/
    └── <id>.md        optional, one file per task

Start each file with a # title and a one-paragraph description:

docs/overview.md
# Example

Writes a comment with the HTTP method and path of every operation.

## Setup

Runs on its own and needs no other plugin.

Leave install commands out of the overview. The page already shows them, and validation fails on them. Extension docs has the rules for the overview, guide names, and Markdown. Also ship a README with installation and a Kubb config example, and a license file.

Check the tarball

Build, list the files npm includes, and create a local tarball:

Terminal
npm run build
npm pack --dry-run
npm pack

Check that the dry run lists dist/, kubb-extension.json, docs/, and package.json, with no fixtures, tests, or generated client files. prepack runs the build and the test first.

Publish a version

Set a version that npm does not have yet, then sign in and publish:

Terminal
npm login
npm publish --access public

Submit to the registry

Open a submission issue on kubb-labs/registry. In Source, enter one of these:

You haveEnter
An npm package (pins latest)kubb-plugin-example
A specific npm version[email protected]
An npm pagehttps://www.npmjs.com/package/kubb-plugin-example
A package on npm, by its folder in a GitHub monorepohttps://github.com/acme/kubb-plugins/tree/main/packages/example
A GitHub release, package not on npmhttps://github.com/acme/kubb-plugin-example/tree/v1.0.0

In Categories, tick every category that fits. The first tick is the main one.

Within minutes, a workflow opens a review pull request with the record and links it on your issue. If the workflow reports a problem instead, fix it and edit the issue to submit again. Your id is <owner>/<slug>, such as acme/kubb-plugin-example.

Wait for the review

Checks on the pull request validate the record and the docs, and load your extension with install scripts off. A maintainer then reviews the package against REVIEW.md.

After the pull request exists, editing the issue no longer submits it again. When a check fails or the maintainer asks for changes, publish a fixed version and reply in the pull request. See Registry checks.

After the merge, the registry lists the extension within minutes. Users install it with:

Terminal
kubb add acme/kubb-plugin-example

Release a new version

A new version does not change what kubb add installs. Every Monday, a workflow opens a pull request that moves each pin to the latest npm version or GitHub release, with the same review. After the merge, users get it with kubb update.

Less common cases

Registry checks

When the registry reviews a version you submit, it reads kubb-extension.json and docs/ from the npm tarball or GitHub release, plus package.json for a GitHub release. Ship these files before you submit.

See Check the tarball and Manifest validation.