@kubb/kit

Documentation · Report Bug · Request Feature

@kubb/kit

Authoring toolkit for Kubb plugins

@kubb/kit gathers the helpers you call when you author a plugin, generator, adapter, resolver, parser, or renderer: defineExtension, defineGenerator, createResolver, createRenderer, the ast namespace and factory node builders, and the option and hook types that go with them. It sits next to the kubb package, which is where end users configure and run builds. kubb/kit re-exports this package, so most consumers reach it through kubb/kit rather than installing @kubb/kit directly.

Installation

Install kubb and import from the kubb/kit subpath, rather than depending on @kubb/kit directly.

bun add kubb
# or
pnpm add kubb
# or
npm install kubb

Usage

import { ast, defineExtension, defineGenerator } from 'kubb/kit'

export const pluginExample = defineExtension({
  kind: 'plugin',
  meta: { name: 'plugin-example' },
  setup(_options, kubb) {
    kubb.addGenerator(
      defineGenerator({
        name: 'example',
        schema(node) {
          return [
            ast.factory.createFile({
              path: `${node.name}.ts`,
              baseName: `${node.name}.ts`,
              sources: [ast.factory.createSource({ nodes: [ast.factory.createText(`// ${node.name}\n`)] })],
              imports: [],
              exports: [],
            }),
          ]
        },
      }),
    )
    return {}
  },
})

What is in the box

defineExtension wraps a plugin, an adapter, or a parser into the shape the build engine expects. Set kind to 'plugin', 'adapter', or 'parser'. definePlugin, defineParser, and createAdapter still work but are deprecated in favor of it. defineGenerator and createResolver wrap a generator or a resolver. createRenderer and createStorage are the matching factories for a custom output renderer or storage backend.

ast and factory are the node builders a generator calls to construct the file, schema, and operation nodes it returns. Diagnostics is the structured error a plugin throws to report a problem with a location and a fix suggestion, and memoryStorage and fsStorage are the built-in storage backends, useful in tests and custom configs.

macroDiscriminatorEnum, macroEnumName, macroRenameSchema, and macroSimplifyUnion are the built-in macro presets, ready to pass to ast.applyMacros or a plugin's setMacros. Build a custom macro with ast.defineMacro instead.

childName, enumPropName, extractRefName, isStringType, mergeAdjacentObjectsLazy, syncSchemaRef, and containsCircularRef are schema-name and schema-graph helpers a generator or macro calls while shaping output, complementing the ref and graph helpers (resolveRefName, findCircularSchemas, collectUsedSchemaNames) that stay on ast.

Rounding out the package are the option and hook types every plugin, generator, adapter, resolver, and renderer author references, among them PluginType, GeneratorContext, ResolveFileOptions, AdapterFactoryOptions, RendererFactory, and KubbHooks.

Testing helpers

kubb/kit/testing holds the Vitest-backed test helpers (createMockedPlugin, createMockedAdapter, renderGeneratorOperation, matchFiles) used to unit test a plugin or generator without running a full build. It is a separate entry point so the main kubb/kit import never pulls in Vitest.

import { createMockedPlugin, renderGeneratorSchema } from 'kubb/kit/testing'

Why a separate package from @kubb/core

@kubb/core also runs the build engine: the plugin driver, the file manager, and the CLI reporters. None of that is part of authoring a plugin. @kubb/kit keeps the two apart, the same way the surrounding kubb/ast and kubb/jsx subpaths separate the AST layer and the JSX renderer from the engine that drives them.

Supporting Kubb

Kubb is an open source project, and its development is funded entirely by sponsors. If you would like to become a sponsor, please consider:

• Become a Sponsor on GitHub
• See sponsorship tiers and our sponsors

License

MIT