Skip to content
Tags
typescripttypesinterfacescodegenopenapi
Details
  • Updated 2 days ago
  • Created 2 years ago
Official v5.0.0-beta.42 MIT kubb >=5.0.0 node >=22

@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

shell
bun add -d @kubb/plugin-ts@beta
shell
pnpm add -D @kubb/plugin-ts@beta
shell
npm install --save-dev @kubb/plugin-ts@beta
shell
yarn add -D @kubb/plugin-ts@beta

Options

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.

typescript
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' },
    }),
  ],
})
text
src/
└── gen/
    └── types/
        ├── Pet.ts
        └── Store.ts

output.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' } uses export *. Smaller barrel file, but exports everything.
  • { nested: true } creates a barrel in every subdirectory, so callers can import from any depth.
  • false skips the barrel entirely. The plugin's files are also excluded from the root index.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.

typescript
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' } },
    }),
  ],
})
typescript
export { Pet, PetStatus } from './Pet'
export { Store } from './Store'
typescript
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' } },
    }),
  ],
})
typescript
export * from './Pet'
export * from './Store'
typescript
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 } },
    }),
  ],
})
text
src/gen/types/
├── index.ts          # re-exports ./petController and ./storeController
├── petController/
│   ├── index.ts      # re-exports Pet, Store, ...
│   └── Pet.ts
└── storeController/
    ├── index.ts
    └── Store.ts
typescript
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: false },
    }),
  ],
})
text
# 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
typescript
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',
      },
    }),
  ],
})
typescript
/* eslint-disable */
// @ts-nocheck
export type Pet = {
  id: number
  name: string
}
typescript
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()}`,
      },
    }),
  ],
})

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
typescript
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.

typescript
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
typescript
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.

typescript
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:

text
src/gen/
├── petController/
│   ├── AddPet.ts
│   └── GetPet.ts
└── storeController/
    ├── CreateStore.ts
    └── GetStoreById.ts

group.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 const object plus a key/value type. Tree-shakeable, no enum runtime.
  • 'asPascalConst' — same as asConst, but the const is named in PascalCase.
  • 'enum' — a regular TypeScript enum. Produces JavaScript runtime code.
  • 'constEnum' — a const 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.

typescript
enum PetType {
  Dog = 'dog',
  Cat = 'cat',
}
typescript
export const petType = {
  Dog: 'dog',
  Cat: 'cat',
} as const

export type PetTypeKey = (typeof petType)[keyof typeof petType]
typescript
export const PetType = {
  Dog: 'dog',
  Cat: 'cat',
} as const

export type PetTypeKey = (typeof PetType)[keyof typeof PetType]
typescript
const enum PetType {
  Dog = 'dog',
  Cat = 'cat',
}
typescript
export type PetType = 'dog' | 'cat'
typescript
// 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'
typescript
export const petType = {
  Dog: 'dog',
  Cat: 'cat',
} as const

export type PetTypeKey = (typeof petType)[keyof typeof petType]
typescript
export const petType = {
  Dog: 'dog',
  Cat: 'cat',
} as const

export type PetTypeValue = (typeof petType)[keyof typeof petType]
typescript
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'
typescript
export type Pet = {
  name: string
}
typescript
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 be undefined.
  • 'questionTokenAndUndefined'type?: string | undefined. Strictest — the property may be missing or explicitly set to undefined.
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.

typescript
export type Pet = {
  type?: string
}
typescript
export type Pet = {
  type: string | undefined
}
typescript
export type Pet = {
  type?: string | undefined
}

arrayType

Syntax used for array types in generated code.

  • 'array' (default) — postfix Type[]. Slightly shorter.
  • 'generic'Array<Type>. More readable for complex element types (Array<{ id: number }>).
Type: 'array' | 'generic'
Required: false
Default: 'array'
typescript
export type Pet = {
  tags: string[]
}
typescript
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.

typescript
// 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
}
typescript
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.

Add an Api prefix to every name
typescript
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')}`
        },
      },
    }),
  ],
})
typescript
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's operationId.
  • 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
Type definition
typescript
export type Include = {
  type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType'
  pattern: string | RegExp
}
typescript
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' },
      ],
    }),
  ],
})
typescript
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's operationId.
  • 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
Type definition
typescript
export type Exclude = {
  type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType'
  pattern: string | RegExp
}
typescript
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' },
      ],
    }),
  ],
})
typescript
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
Type definition
typescript
export type Override = {
  type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType'
  pattern: string | RegExp
  options: PluginOptions
}
typescript
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.

typescript
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 }
        },
      },
    }),
  ],
})
typescript
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
typescript
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', [])
          },
        },
      },
    }),
  ],
})
typescript
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

typescript
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',
    }),
  ],
})

See Also