Shared plugin options
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
{ path: 'types', barrel: { type: 'named' } } on @kubb/plugin-ts.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.import { pluginTs } from '@kubb/plugin-ts'
pluginTs({
output: { path: 'models', barrel: { type: 'named' }, banner: '/* eslint-disable */' },
})output.path
output.path. Required in output. Default: set by each plugin.output.mode
'file' when output.path has an extension, 'directory' otherwise.output.path. Add group to split them into subfolders.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'.
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
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
- pet/
- models/
export { Pet, User } from './models'export { getPetById, getInventory } from './clients'
export *.See @kubb/plugin-barrel options for nested and namespace, and Barrel rules for the fallback to the root output.barrel.
import { pluginZod } from '@kubb/plugin-zod'
pluginZod({ output: { path: 'zod', barrel: { type: 'all', nested: true } } })output.banner
'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:
| Field | Value |
|---|---|
filePath | The file's full output path |
baseName | The file name, such as pet.ts |
isBarrel | true for an index.ts barrel |
isAggregation | true for a group [dir]/[dir].ts aggregation file |
import { pluginFetch } from '@kubb/plugin-fetch'
pluginFetch({
output: {
path: 'clients',
banner: (meta) => (meta.isBarrel || meta.isAggregation ? '' : "'use server'"),
},
})output.footer
output.banner. Default: none.Pair banner: '/* eslint-disable */' with footer: '/* eslint-enable */' to scope a lint disable to each file.
group
{output.path}/{groupName}/ subfolder, named after its tag or URL path. Default: no grouping.group: { type: 'tag' } splits the output by the operation tag, so placeOrder follows its order tag.import { pluginTs } from '@kubb/plugin-ts'
pluginTs({ group: { type: 'tag' } }) // src/gen/types/pet/, src/gen/types/store/, ...group.type
group.default group. See Group folders for OpenAPI 3.2 parent tags.pet for /pet/{petId}.group.name
pet store becomes petStore.import { pluginTs } from '@kubb/plugin-ts'
pluginTs({
group: { type: 'tag', name: ({ group }) => `${group}Api` }, // src/gen/types/petApi/
})include
How filters match
include, exclude, and override entries share one shape: a type, and usually a pattern. Every type except schemaName matches operations.
type | Tests pattern against |
|---|---|
tag | Each operation tag |
operationId | The operationId |
path | The full URL path, such as /pet/{petId} |
method | The HTTP method, ignoring case |
contentType | Each request body content type |
schemaName | The #/components/schemas name, for schemas |
extension | No pattern. Matches an x-* key on the operation, and value by strict equality when set |
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.
export type Include =
| { type: 'tag' | 'operationId' | 'path' | 'contentType' | 'schemaName'; pattern: string | RegExp }
| { type: 'method'; pattern: HttpMethod | RegExp }
| { type: 'extension'; key: `x-${string}`; value?: unknown }import { pluginTs } from '@kubb/plugin-ts'
pluginTs({
include: [
{ type: 'tag', pattern: 'pet' },
{ type: 'path', pattern: /^\/store/ },
],
})Precedence
exclude
exclude wins. Default: [].import { pluginTs } from '@kubb/plugin-ts'
pluginTs({
exclude: [
{ type: 'tag', pattern: 'internal' },
{ type: 'operationId', pattern: /^deprecated_/ },
{ type: 'extension', key: 'x-internal', value: true },
],
})override
[].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.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
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.
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
}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
[].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.
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
schemaNameentries filter schemas by name. - An
includewith operation entries and noschemaNameentry keeps only the schemas those operations use, also indirectly. - An
includewith onlyschemaNameentries generates no operations.
A matching override entry applies its options like this:
optionstakes any plugin option exceptoverride.- An
outputwithoutmodereads it fromoutput.path.
Group folders
With group, the resolver's groupDir(group, value) picks each file's folder. See Built-in members.
| Group | Folder |
|---|---|
A custom group.name | What 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 |
