@kubb/plugin-ts
Generate TypeScript types and interfaces from OpenAPI schemas with full type safety end to end.
- Downloads
- 575k / mo
- Stars
- 3
- Bundle size
- 564.5 kB
- Updated
- 2d ago
@kubb/plugin-ts
@kubb/plugin-ts turns your OpenAPI schema into TypeScript type aliases and interface declarations. It is the foundation that every other Kubb plugin builds on — clients, query hooks, mocks, and validators all reference the names this plugin produces.
Add it once and every request payload, response, path parameter, and enum becomes a compile-time check.
See also
Installation
bun add -d @kubb/plugin-ts@betapnpm add -D @kubb/plugin-ts@betanpm install --save-dev @kubb/plugin-ts@betayarn add -D @kubb/plugin-ts@betaOptions
output
Where the generated .ts files are written and how they are exported.
| Type: | Output |
|---|---|
| Required: | false |
| Default: | { path: 'types', barrel: { type: 'named' } } |
output.path
Folder (or single file) where the plugin writes its generated code. The path is resolved against the global output.path set on defineConfig.
Use a folder to keep each generator's output isolated ('types', 'clients', 'hooks'). Use a single file when you want everything in one place, for example 'api.ts'.
| Type: | string |
|---|---|
| Required: | true |
| Default: | 'types' |
TIP
When output.path points to a single file, the group option cannot be used because every operation ends up in the same file.
import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
output: { path: './types' },
}),
],
})src/
└── gen/
└── types/
├── Pet.ts
└── Store.tsoutput.barrel
Controls how the generated index.ts (barrel) file re-exports the plugin's output.
{ type: 'named' }re-exports each symbol by name. Best for tree-shaking and explicit imports.{ type: 'all' }usesexport *. Smaller barrel file, but exports everything.{ nested: true }creates a barrel in every subdirectory, so callers can import from any depth.falseskips the barrel entirely. The plugin's files are also excluded from the rootindex.ts.
| Type: | { type: 'named' | 'all', nested?: boolean } | false |
|---|---|
| Required: | false |
| Default: | { type: 'named' } |
TIP
Pick 'named' when consumers care about which symbols they import (better tree-shaking, friendlier auto-import). Pick 'all' when the file count is small and you want a one-line barrel.
import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
output: { barrel: { type: 'named' } },
}),
],
})export { Pet, PetStatus } from './Pet'
export { Store } from './Store'import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
output: { barrel: { type: 'all' } },
}),
],
})export * from './Pet'
export * from './Store'import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
output: { barrel: { type: 'named', nested: true } },
}),
],
})src/gen/types/
├── index.ts # re-exports ./petController and ./storeController
├── petController/
│ ├── index.ts # re-exports Pet, Store, ...
│ └── Pet.ts
└── storeController/
├── index.ts
└── Store.tsimport { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
output: { barrel: false },
}),
],
})# No index.ts is generated for this plugin.
# Its files are also excluded from the root index.ts.output.banner
Text prepended to every generated file. Useful for license headers, lint disables, or @ts-nocheck directives.
Pass a string for a static banner. Pass a function to compute the banner from each file's RootNode (the AST root containing path, schema, and operation context).
| Type: | string | ((node: RootNode) => string) |
|---|---|
| Required: | false |
import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
output: {
banner: '/* eslint-disable */\n// @ts-nocheck',
},
}),
],
})/* eslint-disable */
// @ts-nocheck
export type Pet = {
id: number
name: string
}import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
output: {
banner: (node) => `// Source: ${node.path}\n// Generated at ${new Date().toISOString()}`,
},
}),
],
})output.footer
Text appended at the end of every generated file. The mirror of banner — use it for closing comments, re-enabling lint rules, or marker lines.
Pass a string for a static footer, or a function that receives the file's RootNode and returns the footer text.
| Type: | string | ((node: RootNode) => string) |
|---|---|
| Required: | false |
import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
output: {
banner: '/* eslint-disable */',
footer: '/* eslint-enable */',
},
}),
],
})output.override
Allows the plugin to overwrite hand-written files that share a name with a generated file.
false(default): Kubb skips a file if it already exists and is not marked as generated. This protects manual edits.true: Kubb overwrites any file at the target path, including hand-written ones.
| Type: | boolean |
|---|---|
| Required: | false |
| Default: | false |
WARNING
Enable this only when you are sure the target folder contains nothing you need to keep. Local edits are lost on the next generation.
import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
output: { override: true },
}),
],
})contentType
Selects which request/response media type the generator reads from the OpenAPI spec.
When omitted, Kubb picks the first JSON-compatible media type it finds (application/json, application/vnd.api+json, anything ending in +json). Set this when your spec defines multiple media types for the same operation and you want a non-default one.
| Type: | 'application/json' | (string & {}) |
|---|---|
| Required: | false |
import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
contentType: 'application/vnd.api+json',
}),
],
})group
Splits generated files into subfolders based on the operation's tag, so each tag in your OpenAPI spec gets its own directory.
Without group, every file lands in the plugin's output.path folder. With group, files are bucketed under {output.path}/{groupName}/, where groupName is derived from the operation's first tag.
| Type: | Group |
|---|---|
| Required: | false |
TIP
Use group to mirror your API's domain structure (pet, store, user) in the generated code. Combine it with output.barrel: { type: 'named', nested: true } to get per-tag barrel files.
import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
group: {
type: 'tag',
name: ({ group }) => `${group}Controller`,
},
}),
],
})With the configuration above, the generator emits:
src/gen/
├── petController/
│ ├── AddPet.ts
│ └── GetPet.ts
└── storeController/
├── CreateStore.ts
└── GetStoreById.tsgroup.type
Property used to assign each operation to a group. Required whenever group is set.
Today only 'tag' is supported: Kubb reads the first tag on the operation (operation.getTags().at(0)?.name) and uses it as the group key. Operations without a tag are placed in a default group.
| Type: | 'tag' |
|---|---|
| Required: | true |
NOTE
Required: true* is conditional — only required when the parent group option is used. group itself stays optional.
group.name
Function that turns a group key (the operation's first tag) into a folder/identifier name.
The result is used as both the subdirectory name under output.path and as a suffix when naming aggregate files.
| Type: | (context: GroupContext) => string |
|---|---|
| Required: | false |
| Default: | (ctx) => \${ctx.group}Controller`` |
enumType
How OpenAPI enums are represented in the generated TypeScript.
'asConst'(default) —as constobject plus a key/value type. Tree-shakeable, no enum runtime.'asPascalConst'— same asasConst, but the const is named in PascalCase.'enum'— a regular TypeScriptenum. Produces JavaScript runtime code.'constEnum'— aconst enum. Inlines at compile time; not compatible with--isolatedModules.'literal'— a plain union type ('dog' | 'cat'). No runtime value.'inlineLiteral'— the union is inlined at every usage site instead of giving it a name.
| Type: | 'enum' | 'asConst' | 'asPascalConst' | 'constEnum' | 'literal' | 'inlineLiteral' |
|---|---|
| Required: | false |
| Default: | 'asConst' |
TIP
'asConst' vs 'asPascalConst' differs only in the casing of the const variable: petType vs PetType. The type alias is always PascalCase.
enum PetType {
Dog = 'dog',
Cat = 'cat',
}export const petType = {
Dog: 'dog',
Cat: 'cat',
} as const
export type PetTypeKey = (typeof petType)[keyof typeof petType]export const PetType = {
Dog: 'dog',
Cat: 'cat',
} as const
export type PetTypeKey = (typeof PetType)[keyof typeof PetType]const enum PetType {
Dog = 'dog',
Cat = 'cat',
}export type PetType = 'dog' | 'cat'// No separate enum type — values are inlined wherever PetType would have been used
export interface Pet {
status?: 'available' | 'pending' | 'sold'
}TIP
'inlineLiteral' produces the cleanest output for small enums — the values appear directly where they are used instead of via a named alias.
enumSuffix
| Required: | false |
|---|
WARNING
Moved to adapterOas. Use adapterOas({ enumSuffix }) instead.
enumTypeSuffix
Suffix appended to the type alias generated for enums when enumType is 'asConst' or 'asPascalConst'.
The const object name (e.g. petType) is unaffected — only the companion type alias is renamed.
| Type: | string |
|---|---|
| Required: | false |
| Default: | 'Key' |
export const petType = {
Dog: 'dog',
Cat: 'cat',
} as const
export type PetTypeKey = (typeof petType)[keyof typeof petType]export const petType = {
Dog: 'dog',
Cat: 'cat',
} as const
export type PetTypeValue = (typeof petType)[keyof typeof petType]export const petType = {
Dog: 'dog',
Cat: 'cat',
} as const
export type PetType = (typeof petType)[keyof typeof petType]enumKeyCasing
Casing applied to enum key names. By default the key is the raw value from the spec; switch to a project convention when needed.
| Type: | 'screamingSnakeCase' | 'snakeCase' | 'pascalCase' | 'camelCase' | 'none' |
|---|---|
| Required: | false |
| Default: | 'none' |
| Value | Example key |
|---|---|
'screamingSnakeCase' | ENUM_VALUE |
'snakeCase' | enum_value |
'pascalCase' | EnumValue |
'camelCase' | enumValue |
'none' (default) | as-is |
dateType
| Required: | false |
|---|
WARNING
Moved to adapterOas. Use adapterOas({ dateType }) instead.
integerType
| Required: | false |
|---|
WARNING
Moved to adapterOas. Use adapterOas({ integerType }) instead.
syntaxType
Whether object schemas are emitted as type aliases or interface declarations.
type is the safer default for generated code: declarations are closed, intersections work cleanly, and unions are fine. Pick interface when consumers need to use declaration merging (rare for generated code).
For more background, see Type vs Interface.
| Type: | 'type' | 'interface' |
|---|---|
| Required: | false |
| Default: | 'type' |
export type Pet = {
name: string
}export interface Pet {
name: string
}unknownType
| Required: | false |
|---|
WARNING
Moved to adapterOas. Use adapterOas({ unknownType }) instead.
emptySchemaType
| Required: | false |
|---|
WARNING
Moved to adapterOas. Use adapterOas({ emptySchemaType }) instead.
optionalType
How optional properties are written in generated types.
'questionToken'(default) —type?: string. The property may be missing.'undefined'—type: string | undefined. The property is required to exist but may beundefined.'questionTokenAndUndefined'—type?: string | undefined. Strictest — the property may be missing or explicitly set toundefined.
| Type: | 'questionToken' | 'undefined' | 'questionTokenAndUndefined' |
|---|---|
| Required: | false |
| Default: | 'questionToken' |
TIP
Choose 'questionTokenAndUndefined' when your project enables "exactOptionalPropertyTypes": true in tsconfig.json — it keeps generated types compatible with that setting.
export type Pet = {
type?: string
}export type Pet = {
type: string | undefined
}export type Pet = {
type?: string | undefined
}arrayType
Syntax used for array types in generated code.
'array'(default) — postfixType[]. Slightly shorter.'generic'—Array<Type>. More readable for complex element types (Array<{ id: number }>).
| Type: | 'array' | 'generic' |
|---|---|
| Required: | false |
| Default: | 'array' |
export type Pet = {
tags: string[]
}export type Pet = {
tags: Array<string>
}paramsCasing
Renames properties inside PathParams, QueryParams, and HeaderParams types. Response and request body types are not touched.
Use this when your OpenAPI parameters use snake_case or kebab-case but you want camelCase in TypeScript.
| Type: | 'camelcase' |
|---|---|
| Required: | false |
IMPORTANT
Every plugin that references parameters must use the same paramsCasing value — @kubb/plugin-client, @kubb/plugin-react-query, @kubb/plugin-vue-query, @kubb/plugin-faker, @kubb/plugin-mcp. Mismatched casing breaks the generated type chain.
// OpenAPI spec: step_id, bool_param, X-Custom-Header
export type FindPetsByStatusPathParams = {
step_id: string
}
export type FindPetsByStatusQueryParams = {
bool_param?: boolean
}
export type FindPetsByStatusHeaderParams = {
'X-Custom-Header'?: string
}export type FindPetsByStatusPathParams = {
stepId: string
}
export type FindPetsByStatusQueryParams = {
boolParam?: boolean
}
export type FindPetsByStatusHeaderParams = {
xCustomHeader?: string
}resolver
Overrides how the plugin builds names and paths for generated files and symbols. Use this to add prefixes, suffixes, or to swap the casing strategy without forking the plugin.
Only override the methods you want to change. Anything you omit falls back to the plugin's default resolver. A method that returns null or undefined also falls back.
Inside each method, this is bound to the full resolver, so you can call this.default(name, 'function') to delegate to the built-in implementation.
| Type: | Partial<ResolverTs> & ThisType<ResolverTs> |
|---|---|
| Required: | false |
TIP
Use resolver for naming and file-location tweaks. For changing the AST nodes themselves (e.g. stripping descriptions), use transformer instead.
import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
resolver: {
resolveName(name) {
return `Api${this.default(name, 'function')}`
},
},
}),
],
})import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
resolver: {
resolveName(name) {
return `Custom${this.default(name, 'function')}`
},
},
}),
],
})Each plugin ships with a default resolver:
| Plugin | Default resolver |
|---|---|
@kubb/plugin-ts | resolverTs |
@kubb/plugin-zod | resolverZod |
@kubb/plugin-faker | resolverFaker |
@kubb/plugin-cypress | resolverCypress |
@kubb/plugin-msw | resolverMsw |
@kubb/plugin-mcp | resolverMcp |
@kubb/plugin-client | resolverClient |
include
Restricts generation to operations that match at least one entry in the list. Anything not matched is skipped.
Each entry filters by one of:
tag— the operation's first tag in the OpenAPI spec.operationId— the operation'soperationId.path— the URL pattern ('/pet/{petId}').method— HTTP method ('get','post', ...).contentType— the media type of the request body.
pattern accepts either a string (exact match) or a RegExp for fuzzy matches.
| Type: | Array<Include> |
|---|---|
| Required: | false |
export type Include = {
type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType'
pattern: string | RegExp
}import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
include: [
{ type: 'tag', pattern: 'pet' },
],
}),
],
})import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
include: [
{ type: 'method', pattern: 'get' },
{ type: 'path', pattern: /^\/pet/ },
],
}),
],
})exclude
Skips any operation that matches at least one entry in the list. The opposite of include.
Each entry filters by one of:
tag— the operation's first tag.operationId— the operation'soperationId.path— the URL pattern ('/pet/{petId}').method— HTTP method ('get','post', ...).contentType— the media type of the request body.
pattern accepts a plain string or a RegExp. When both include and exclude are set, exclude wins.
| Type: | Array<Exclude> |
|---|---|
| Required: | false |
export type Exclude = {
type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType'
pattern: string | RegExp
}import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
exclude: [
{ type: 'tag', pattern: 'store' },
],
}),
],
})import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
exclude: [
{ type: 'operationId', pattern: 'deletePet' },
{ type: 'method', pattern: 'delete' },
],
}),
],
})override
Applies a different set of plugin options to operations that match a pattern. Use this when most of your API should follow the global config, but a handful of endpoints need different treatment.
Each entry has the same type and pattern shape as include/exclude, plus an options object that overrides the plugin's options for matched operations.
Entries are evaluated top to bottom. The first matching entry's options is merged onto the plugin defaults; later entries do not stack.
| Type: | Array<Override> |
|---|---|
| Required: | false |
export type Override = {
type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType'
pattern: string | RegExp
options: PluginOptions
}import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
enumType: 'asConst',
override: [
{
type: 'tag',
pattern: 'user',
options: { enumType: 'literal' },
},
],
}),
],
})generators experimental
Adds custom generators that run alongside the plugin's built-in generators. Each generator can emit additional files or post-process existing ones using the plugin's AST and options.
Use this when you need output the plugin does not produce out of the box (a custom client wrapper, an extra index, a metadata file). For end-to-end guidance, see Creating plugins.
| Type: | Array<Generator<PluginTs>> |
|---|---|
| Required: | false |
WARNING
Generators are an experimental, low-level API. The signature may change between minor releases.
transformer
Modifies AST nodes before they are printed to source code. Use this when you need to rewrite operation IDs, drop descriptions, or change schema metadata without forking the generator.
Each visitor method (e.g. schema, operation) receives the node and a context object. Return a new node to replace it, or return undefined to leave it untouched. Methods you omit keep the plugin's default behavior.
| Type: | Visitor |
|---|---|
| Required: | false |
TIP
Use transformer to rewrite node properties before printing. For changing the names of generated symbols and files, use resolver instead.
NOTE
@kubb/plugin-ts uses AST visitors for schema/operation node transforms. For renaming generated symbols, use resolver instead.
import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
transformer: {
schema(node) {
return { ...node, description: undefined }
},
},
}),
],
})import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
transformer: {
operation(node) {
return { ...node, operationId: `api_${node.operationId}` }
},
},
}),
],
})printer
Replaces the TypeScript node handler for a specific schema type (e.g. 'integer', 'date', 'string'). Each handler is a function that builds a TypeScript AST node for that schema type.
Use this.transform to recurse into nested schema nodes and this.options to read printer options.
| Type: | { nodes?: PrinterTsNodes } |
|---|---|
| Required: | false |
import ts from 'typescript'
import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
printer: {
nodes: {
date() {
return ts.factory.createTypeReferenceNode('Date', [])
},
},
},
}),
],
})import ts from 'typescript'
import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
printer: {
nodes: {
integer() {
return ts.factory.createKeywordTypeNode(ts.SyntaxKind.BigIntKeyword)
},
},
},
}),
],
})Example
import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
input: { path: './petStore.yaml' },
output: { path: './src/gen' },
plugins: [
pluginTs({
output: { path: './types' },
exclude: [{ type: 'tag', pattern: 'store' }],
group: {
type: 'tag',
name: ({ group }) => `${group}Controller`,
},
enumType: 'asConst',
optionalType: 'questionTokenAndUndefined',
paramsCasing: 'camelcase',
}),
],
})