Skip to content
Reference

Shared plugin options

The output, group, include, exclude, override, resolver, and macros options every Kubb generator plugin accepts, with types, defaults, and precedence.

Every generator plugin takes these options to set where it writes, what it generates, and how it names files. A plugin's own options page lists only its defaults. @kubb/plugin-barrel takes none and reads output.barrel. @kubb/plugin-redoc takes only output.path.

output

Output
Where the plugin writes its files and how it exports them. Default: set by each plugin, such as { path: 'types', barrel: { type: 'named' } } on @kubb/plugin-ts.
An output you pass replaces the plugin default whole. Repeat barrel in it, or the plugin falls back to the root output.barrel, which is false unless you set it.
kubb.config.ts
import { pluginTs } from '@kubb/plugin-ts'

pluginTs({
  output: { path: 'models', barrel: { type: 'named' }, banner: '/* eslint-disable */' },
})

output.path

string required
The plugin's folder or file, resolved inside the root output.path. Required in output. Default: set by each plugin.

output.mode

'directory' | 'file'
How the plugin splits its code into files. Default: 'file' when output.path has an extension, 'directory' otherwise.
'directory'
Writes one file per operation or schema under output.path. Add group to split them into subfolders.
'file'
Writes everything into one file. output.path must include the extension, such as 'types.ts'.

Set mode: 'directory' only for a folder name with a dot, such as 'clients.v2'.

kubb.config.ts
import { defineConfig } from 'kubb/config'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginAxios } from '@kubb/plugin-axios'

export default defineConfig({
  input: './petStore.yaml',
  output: { path: './src/gen' },
  plugins: [
    pluginTs({ output: { path: 'types.ts' } }), // src/gen/types.ts
    pluginAxios({ output: { path: 'clients' }, group: { type: 'tag' } }), // src/gen/clients/pet/, src/gen/clients/store/
  ],
})

output.barrel

{ type: 'all' | 'named', nested?: boolean, namespace?: boolean } | false
How the plugin's index.ts files re-export its output. Default: { type: 'named' } in the plugin's default output.
  • src/gen/
    • models/
      • Pet.ts
      • User.ts
    • clients/
      • pet/
        • getPetById.ts
      • store/
        • getInventory.ts
src/gen/index.ts
export { Pet, User } from './models'export { getPetById, getInventory }  from './clients'
'named'
Re-exports each symbol by name, for explicit imports and tree-shaking.
'all'
Re-exports every file with export *.
false
Writes no barrel for this plugin and leaves its files out of the root barrel.

See @kubb/plugin-barrel options for nested and namespace, and Barrel rules for the fallback to the root output.barrel.

kubb.config.ts
import { pluginZod } from '@kubb/plugin-zod'

pluginZod({ output: { path: 'zod', barrel: { type: 'all', nested: true } } })

output.banner

string | ((meta: BannerMeta) => string)
Text at the top of every generated file, such as a license header or 'use server'. Default: the root output.defaultBanner.

A string goes on every file, barrels included. A function runs per file and returns the banner, or '' for none. Its BannerMeta holds the InputMeta fields, such as title and version, plus:

FieldValue
filePathThe file's full output path
baseNameThe file name, such as pet.ts
isBarreltrue for an index.ts barrel
isAggregationtrue for a group [dir]/[dir].ts aggregation file
kubb.config.ts
import { pluginFetch } from '@kubb/plugin-fetch'

pluginFetch({
  output: {
    path: 'clients',
    banner: (meta) => (meta.isBarrel || meta.isAggregation ? '' : "'use server'"),
  },
})
string | ((meta: BannerMeta) => string)
Text at the bottom of every generated file, with the same values as output.banner. Default: none.

Pair banner: '/* eslint-disable */' with footer: '/* eslint-enable */' to scope a lint disable to each file.

group

{ type: 'tag' | 'path', name?: (context: { group: string }) => string }
Puts each operation's files in a {output.path}/{groupName}/ subfolder, named after its tag or URL path. Default: no grouping.
getPetById.tsGET /pet/{petId} tag: petaddPet.tsPOST /pet tag: petgetInventory.tsGET /store/inventory tag: storeplaceOrder.tsPOST /store/order tag: ordergetOrderById.tsGET /store/order/{id} tag: orderloginUser.tsGET /user/login tag: userclients/pet/getPetById.tsaddPet.tsclients/store/getInventory.tsclients/order/placeOrder.tsgetOrderById.tsclients/user/loginUser.ts
group: { type: 'tag' } splits the output by the operation tag, so placeOrder follows its order tag.
group needs directory output, or the build stops with KUBB_INVALID_PLUGIN_OPTIONS.
kubb.config.ts
import { pluginTs } from '@kubb/plugin-ts'

pluginTs({ group: { type: 'tag' } }) // src/gen/types/pet/, src/gen/types/store/, ...

group.type

'tag' | 'path' required
Which value assigns an operation to a group. Required in group.
'tag'
The operation's first tag. An operation without tags goes in the default group. See Group folders for OpenAPI 3.2 parent tags.
'path'
The first segment of the URL path, such as pet for /pet/{petId}.

group.name

(context: { group: string }) => string
Turns the group value into the folder name, which is also the suffix of aggregation files. Default: the value in camelCase, so pet store becomes petStore.
kubb.config.ts
import { pluginTs } from '@kubb/plugin-ts'

pluginTs({
  group: { type: 'tag', name: ({ group }) => `${group}Api` }, // src/gen/types/petApi/
})

include

Array<Include>
Generates only the operations and schemas that match an entry. Default: everything.

How filters match

include, exclude, and override entries share one shape: a type, and usually a pattern. Every type except schemaName matches operations.

typeTests pattern against
tagEach operation tag
operationIdThe operationId
pathThe full URL path, such as /pet/{petId}
methodThe HTTP method, ignoring case
contentTypeEach request body content type
schemaNameThe #/components/schemas name, for schemas
extensionNo pattern. Matches an x-* key on the operation, and value by strict equality when set
A string pattern becomes new RegExp(pattern), so it matches anywhere: 'pet' also matches 'petType'. Write '^pet$' for an exact match.

Without a schemaName entry, include keeps only the schemas its operations use. See Filters.

Type definition
export type Include =
  | { type: 'tag' | 'operationId' | 'path' | 'contentType' | 'schemaName'; pattern: string | RegExp }
  | { type: 'method'; pattern: HttpMethod | RegExp }
  | { type: 'extension'; key: `x-${string}`; value?: unknown }
kubb.config.ts
import { pluginTs } from '@kubb/plugin-ts'

pluginTs({
  include: [
    { type: 'tag', pattern: 'pet' },
    { type: 'path', pattern: /^\/store/ },
  ],
})

Precedence

yesnoyesnoyesnoOperation or schemaMatches an exclude entry?Skippedinclude set and no entrymatches?An override entry matches?Plugin options + first matchPlugin options

exclude

Array<Exclude>
Skips every operation or schema that matches an entry. Entries match as in How filters match, and exclude wins. Default: [].
kubb.config.ts
import { pluginTs } from '@kubb/plugin-ts'

pluginTs({
  exclude: [
    { type: 'tag', pattern: 'internal' },
    { type: 'operationId', pattern: /^deprecated_/ },
    { type: 'extension', key: 'x-internal', value: true },
  ],
})

override

Array<Override>
Gives matching operations or schemas other plugin options. Entries match as in How filters match, top to bottom. Only the first match applies. Default: [].
Type definition
export type Override = Include & {
  options: Omit<Partial<ResolvedOptions>, 'override'>
}
options merges shallowly over the plugin options, so an object option such as enum replaces the plugin's value whole. Give it every field.
kubb.config.ts
import { pluginTs } from '@kubb/plugin-ts'

pluginTs({
  override: [
    {
      type: 'tag',
      pattern: 'admin',
      options: {
        output: { path: 'admin' },
        enum: { type: 'enum', constCasing: 'camelCase', typeSuffix: 'Key', keyCasing: 'none' },
      },
    },
  ],
})

resolver

ResolverPatch<Resolver>
Changes how the plugin names generated files and symbols. Members you leave out keep the plugin's behavior. Default: the plugin's resolver.

Every resolver has these members. A plugin's options page lists its own, such as param on @kubb/plugin-ts. In a method, this is the full resolver, so this.default.name(name) reuses the built-in casing.

Shared members
type ResolverPatch = {
  name?(name: string): string // the identifier for a name
  file?: {
    baseName?(params: { name: string; extname: string }): string // the file name, extension included
    path?(params: { baseName: string; output: Output }): string // the full path, which skips output.path and group
  }
  imports?(options: ResolveImportsOptions): Array<ImportNode> // the imports for the $ref schemas a node uses
}
kubb.config.ts
import { pluginTs } from '@kubb/plugin-ts'

pluginTs({
  resolver: {
    name(name) {
      return `${this.default.name(name)}Model` // Pet becomes petModel
    },
  },
})

See Resolvers for how a patch layers over the default.

macros

Array<Macro>
Rewrite AST nodes before the plugin prints them, without forking its generator. Default: [].

Macros run in order, each on the previous output. @kubb/plugin-fetch, @kubb/plugin-axios, and @kubb/plugin-client run their built-in macros first.

kubb.config.ts
import { defineMacro } from 'kubb/kit'
import { pluginTs } from '@kubb/plugin-ts'

const macroUntagged = defineMacro({
  name: 'untagged',
  operation(node) {
    return node.tags?.length ? undefined : { ...node, tags: ['untagged'] }
  },
})

pluginTs({ macros: [macroUntagged] })

See Macros for a walkthrough, and ast.macro for callbacks and built-in macros.

Less common cases

Filters

When an include or exclude mixes operation and schemaName entries, schemas follow their own rules.

  • Only schemaName entries filter schemas by name.
  • An include with operation entries and no schemaName entry keeps only the schemas those operations use, also indirectly.
  • An include with only schemaName entries generates no operations.

A matching override entry applies its options like this:

  • options takes any plugin option except override.
  • An output without mode reads it from output.path.

Group folders

With group, the resolver's groupDir(group, value) picks each file's folder. See Built-in members.

GroupFolder
A custom group.nameWhat group.name returns. It wins over type.
type: 'tag'The camelCased tag, inside the folders of its OpenAPI 3.2 parent tags, such as animals/cats/
type: 'path'The first path segment