Skip to content
Reference

Extension registry

Reference for the Kubb extension registry protocol at kubb.dev/registry, its index and detail documents, registry ids, records that pin one npm version, and how to host your own registry.

The Kubb extension registry lists reviewed plugins, adapters, and parsers. Each entry pins one npm version. kubb add, kubb update, kubb list, kubb.dev, and Kubb Studio read it.

The base URL is https://kubb.dev/registry. The registry is a set of plain static JSON documents:

  • Served as application/json, with CORS allowed, so any site or tool can read them.
  • Answered directly, never through a redirect.
  • Cached for 10 minutes (cache-control: public, max-age=600).

kubb-labs/registry builds the documents on every merge and once a day, and kubb.dev serves them at its base URL.

Registry ids

An id is <owner>/<slug>, such as kubb-labs/plugin-zod:

  • <owner> is the GitHub owner of the source repository, in lowercase.
  • <slug> is the npm package name without its scope. @kubb/plugin-zod gives plugin-zod.
  • Both parts match [a-z0-9]+(?:-[a-z0-9]+)*: lowercase letters and digits joined by single hyphens.

The CLI accepts a bare <slug> and reads it as kubb-labs/<slug>. An entry owned by kubb-labs has type: "official". Every other entry is community.

GET <base>/index.json

Returns every extension in the registry:

type RegistryIndex = {
  version: 1
  generatedAt: string
  extensions: Array<RegistryEntry>
}

The CLI rejects an index whose version is not 1. It skips an entry that fails validation and keeps the rest.

GET <base>/<owner>/<slug>.json

Returns one extension and its overview:

type RegistryDetail = RegistryEntry & { overview: string | null }

overview is the Markdown of the package's OVERVIEW.md, or the overview the reviewer wrote. An unknown id answers 404, and kubb add reports "<id>" is not in the registry at <registry>.

RegistryEntry

@kubb/core exports the RegistryEntry, RegistryIndex, and RegistryDetail types.

id

string required
The registry id, such as kubb-labs/plugin-zod.

kind

'plugin' | 'adapter' | 'parser' required
The extension kind. It always equals manifest.kind.

type

'official' | 'community' required
official when the owner is kubb-labs, otherwise community.

artifact

{ kind: 'npm'; package: string; version: string } required
The install pin: the npm package and the exact version the registry approved. kubb add and kubb update install <package>@<version>.

repository

{ url: string }
The source on GitHub, optionally pointing at the package folder.

manifest

ExtensionManifest required
The kubb-extension.json of the pinned version, with the reviewer's main category and listing overrides applied. For an official version released before manifests, the registry builds it from the frontmatter of the package's page in this documentation.

stats

{ downloads?: number; weekly?: number; stars?: number }
Download and star counts, when known.

submittedAt

string required
When the extension was submitted. It never changes.

publishedAt

string required
When the first version was approved and listed. It never changes.

reviewedAt

string required
When the pinned version was approved. Every version bump moves it.

Timestamps are UTC, to the second, such as 2026-10-12T20:00:00Z.

The CLI checks each entry before it uses it. The id must be a full <owner>/<slug>, artifact.kind must be npm, artifact.package a valid npm package name, artifact.version a valid semver version, and manifest a valid manifest whose kind equals the entry's kind. The detail document's id must also equal the id the CLI asked for.

Records

The reviewed records live in kubb-labs/registry at extensions/<owner>/<slug>.json. The registry's build turns them into the documents above. Merging a record approves its pinned version.

extensions/kubb-labs/plugin-zod.json
{
  "$schema": "https://kubb.dev/schemas/registry-record.json",
  "id": "kubb-labs/plugin-zod",
  "artifact": { "kind": "npm", "package": "@kubb/plugin-zod", "version": "5.4.4" },
  "repository": { "url": "https://github.com/kubb-labs/plugins/tree/main/packages/plugin-zod" },
  "submittedAt": "2026-10-12T20:11:53Z",
  "submittedBy": "stijnvanhulle",
  "publishedAt": "2026-10-12T20:11:53Z",
  "reviewedAt": "2026-10-12T20:11:53Z",
  "categories": ["validation"]
}
FieldWritten byMeaning
idBot<owner>/<slug>. Must equal the file path.
artifactBotThe install pin: an exact npm version.
repository.urlBotThe source on GitHub, optionally the package folder.
submittedAtBotWhen the extension was submitted. Never changes.
submittedByBotThe GitHub user who opened the submission.
publishedAtBotWhen the first version was approved. Never changes.
reviewedAtBotWhen the pinned version was approved. Every bump moves it.
categoriesReviewerCategory slugs. The first is the main one and replaces the manifest's category.
listingReviewerOptional overrides for displayName, description, tags, and icon.

The record JSON Schema is https://kubb.dev/schemas/registry-record.json. To add a record, follow Publish a plugin.

Categories

SlugUse for
typesGenerate TypeScript types and interfaces.
validationValidate data at runtime with schemas.
clientGenerate HTTP clients that call the API.
frameworkGenerate hooks and composables for UI frameworks.
mocksGenerate mock data and mock servers.
testingGenerate tests and test helpers.
documentationGenerate API documentation.
aiExpose the API to AI agents and tools.
outputShape the generated files, such as barrel files.
openapiRead OpenAPI and Swagger specs.
typescriptPrint generated code as TypeScript.
docsPrint generated code as Markdown.

Host your own registry

Serve the same two documents from any static host, then point the CLI at it with KUBB_REGISTRY. To build them from your own records, fork kubb-labs/registry, replace extensions/, and run pnpm build. The dist/ folder is the whole registry.

Terminal
KUBB_REGISTRY=https://registry.example.com kubb add acme/plugin-graphql

With that base URL, the CLI reads https://registry.example.com/index.json and https://registry.example.com/acme/plugin-graphql.json. KUBB_REGISTRY must start with http:// or https://, and trailing slashes are removed.

Your documents must follow the shapes on this page, and index.json must set version: 1. Answer 404 for an unknown id. Studio always reads the kubb.dev index, so a private registry changes what the CLI installs, not what Studio lists.

See also

HTTP serialization

Architecture