Open Studio
Kit

Plugins

definePlugin wraps a factory into a typed Plugin, with all lifecycle handlers under one hooks object and the KubbPluginSetupContext that registers generators, resolvers, macros, and options.

Plugins are the main extension point in Kubb. A plugin owns its file naming, its output folder, its lifecycle hooks, and the generators that walk the AST and emit FileNode objects.

definePlugin ​

definePlugin wraps a factory function and returns a typed Plugin. All lifecycle handlers live under one hooks object, inspired by Astro integrations.

plugin-example.ts
typescript
import { definePlugin } from 'kubb/kit'

export const pluginExample = definePlugin((options: { prefix?: string } = {}) => ({
  name: 'plugin-example',
  hooks: {
    'kubb:plugin:setup'(ctx) {
      // Register resolvers, generators, and options here.
    },
  },
}))

Plugin shape ​

PropertyTypeRequiredDescription
namestringYesUnique plugin identifier (e.g., plugin-ts)
dependenciesArray<string>NoNames of other plugins this one requires
enforce'pre' | 'post'NoRun this plugin before ('pre') or after ('post') the normal plugins. Dependency order still wins.
optionsunknownNoUser-supplied options passed through to generators
hooks{ 'kubb:plugin:setup'?: ...; ... }YesLifecycle handlers (see Plugin API)

KubbPluginSetupContext methods (passed to kubb:plugin:setup) ​

MethodSignaturePurpose
addGenerator(...generators: Array<Generator>) => voidRegister one or more generators for this plugin
setResolver(resolver: ResolverPatch<Resolver> | Resolver) => voidSet or partially override the file naming resolver
addMacro(macro: Macro) => voidAdd a macro that rewrites AST nodes before generators
setMacros(macros: Array<Macro>) => voidReplace this plugin's macros with a new list
setOptions(options: ResolvedOptions) => voidSet the resolved options used by generators
injectFile(file: UserFileNode) => voidInject a raw file into the build output, bypassing generation
configConfigThe resolved build configuration at setup time
optionsTOptionsThe plugin's own options as passed by the user

Important

Plugin names should follow the convention plugin-<feature> (e.g., plugin-react-query, plugin-zod). See Creating plugins for naming conventions.

Overview

Generators