Publish a plugin
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.
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:
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:
{
"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:
filesships the build, the manifest, and thedocs/folder.exportslistskubb-extension.jsonandpackage.json, because anexportsmap hides every path it does not list.repositorypoints to a GitHub repository you own, or one in an organization you belong to.kubbor@kubb/coreis a peer dependency, not a bundled one. Keepkubbas a dev dependency too, to build and test locally.- A
preinstall,install, orpostinstallscript 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:
{
"$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
nameto the plugin'smeta.nameandexportto the factory thatsrc/index.tsexports. - Give
meta.compatibilityinsrc/plugin.tsthe same ranges, so Kubb checks them at runtime too. With a bundler, importcompatibilityfrom 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/
├── overview.md required
├── options.md optional, the full option reference
└── guides/
└── <id>.md optional, one file per taskStart each file with a # title and a one-paragraph description:
# 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:
npm run build
npm pack --dry-run
npm packCheck 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:
npm login
npm publish --access publicIf the package is not on npm, users install it from a GitHub release. kubb add installs github:<owner>/<repo>#<commit>, so nothing builds on the user's machine. The release must meet these rules:
- The package sits at the repository root. A scoped name uses your GitHub owner, such as
@acme/forgithub.com/acme. dist/is committed.main,module, andexportspoint to committed files, andfileslists them andkubb-extension.json.package.jsonhas nopreinstall,install,postinstall,prepare,prepack,prepublish,publish, orbuildscript, and noworkspaces. Renamebuild, for example tocompile, and dropprepack.- The tag equals the
package.jsonversion, with or without a leadingv, such asv1.0.0.
Commit the manifest, the docs, and the build, then create a GitHub release from that commit.
Submit to the registry
Open a submission issue on kubb-labs/registry. In Source, enter one of these:
| You have | Enter |
|---|---|
An npm package (pins latest) | kubb-plugin-example |
| A specific npm version | [email protected] |
| An npm page | https://www.npmjs.com/package/kubb-plugin-example |
| A package on npm, by its folder in a GitHub monorepo | https://github.com/acme/kubb-plugins/tree/main/packages/example |
| A GitHub release, package not on npm | https://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:
kubb add acme/kubb-plugin-exampleRelease 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.
