TypeScript

Officialv5.0.9

@kubb/plugin-ts

Options

Pass these options to pluginTs(). Shared options link to Shared plugin options for details.

Options overview

Option	Purpose	Default
`output`	Where files are written: `path`, `mode`, `barrel`, `banner`, `footer`.	`{ path: 'types', barrel: { type: 'named' } }`
`group`	Split output by tag or path: `type`, `name`.	None
`enum`	How enums are generated and cased.	`{ type: 'asConst', constCasing: 'camelCase', typeSuffix: 'Key', keyCasing: 'none' }`
`syntaxType`	Emit object schemas as type aliases or interfaces.	`'type'`
`optionalType`	How optional properties are written.	`'questionToken'`
`arrayType`	`Type[]` or `Array<Type>`.	`'array'`
`include`	Keep only operations and schemas that match.	None
`exclude`	Skip operations and schemas that match.	`[]`
`override`	Apply different options per pattern.	`[]`
`resolver`	Customize generated names and file paths.	`resolverTs`
`macros`	Rewrite AST nodes before printing.	`[]`
`printer`	Replace the handler for a schema type.	None

Option details

enum

How OpenAPI enums are represented in the generated TypeScript, and how their names are cased.


Type	`{ type?, constCasing?, typeSuffix?, keyCasing? }`
Required	`false`
Default	`{ type: 'asConst', constCasing: 'camelCase', typeSuffix: 'Key', keyCasing: 'none' }`

constCasing and typeSuffix apply only to type: 'asConst'. keyCasing applies to 'asConst', 'enum' and 'constEnum', since the literal modes emit values only.

enum.type

Representation of each enum.


Type	`'asConst' \| 'enum' \| 'constEnum' \| 'literal' \| 'inlineLiteral'`
Required	`false`
Default	`'asConst'`

'asConst'

Emits an as const object and a union type of its values. Bundlers drop the object when nothing uses it.

'enum'

Emits a TypeScript enum with JavaScript runtime code.

'constEnum'

Emits a const enum, inlined at compile time and incompatible with --isolatedModules.

'literal'

Emits a named union type with no runtime value.

'inlineLiteral'

Emits the same union as 'literal' but inlines it at each usage site instead of naming it.

export const petStatus = {
  available: 'available',
  pending: 'pending',
  sold: 'sold',
} as const

export type PetStatusKey = (typeof petStatus)[keyof typeof petStatus]

export enum PetStatus {
  available = 'available',
  pending = 'pending',
  sold = 'sold',
}

export type PetStatus = 'available' | 'pending' | 'sold'

enum.constCasing

Casing of the generated const object when type is 'asConst'.


Type	`'camelCase' \| 'pascalCase'`
Required	`false`
Default	`'camelCase'`

'camelCase'

Names the const petStatus.

'pascalCase'

Names the const PetStatus, matching the schema name.

Suffix on the companion type alias when type is 'asConst'. It never changes the const object name. Set it to '' to drop the suffix, which with constCasing: 'pascalCase' merges the const and the type under one name, PetStatus.


Type	`string`
Required	`false`
Default	`'Key'`

typeSuffix: 'Value'

export type PetStatusValue = (typeof petStatus)[keyof typeof petStatus]

enum.keyCasing

Casing applied to enum key names.


Type	`'none' \| 'camelCase' \| 'pascalCase' \| 'snakeCase' \| 'screamingSnakeCase'`
Required	`false`
Default	`'none'`

'none'

Keeps the raw enum value from the spec as the key.

'camelCase'

Formats keys as enumValue.

'pascalCase'

Formats keys as EnumValue.

'snakeCase'

Formats keys as enum_value.

'screamingSnakeCase'

Formats keys as ENUM_VALUE.

syntaxType

How object schemas are declared.


Type	`'type' \| 'interface'`
Required	`false`
Default	`'type'`

'type'

Generates type aliases, export type Pet = { name: string }.

'interface'

Generates interface declarations, export interface Pet { name: string }. Use it when consumers need declaration merging. See Type vs Interface.

optionalType

How optional properties are written.


Type	`'questionToken' \| 'undefined' \| 'questionTokenAndUndefined'`
Required	`false`
Default	`'questionToken'`

'questionToken'

Writes type?: string, so the property may be missing.

'undefined'

Writes type: string | undefined, so it must exist but may be undefined.

'questionTokenAndUndefined'

Writes type?: string | undefined, so the property may be missing or undefined. Use it with "exactOptionalPropertyTypes": true.

arrayType

Syntax for array types.


Type	`'array' \| 'generic'`
Required	`false`
Default	`'array'`

'array'

Uses the postfix tags: string[].

'generic'

Uses tags: Array<string>, which reads better for complex elements like Array<{ id: number }>.

resolver

Overrides generated file and symbol names. Omitted members keep resolverTs. The shared members (name, file, imports) and the this context are described under resolver.


Type	`ResolverPatch<ResolverTs>`
Required	`false`

Partial override

type ResolverTsPatch = {
  // plus the shared name, file, and imports members
  param?: {
    name?(node: OperationNode, param: ParameterNode): string    // → 'DeletePetPathPetId'
    path?(node: OperationNode, param: ParameterNode): string     // → 'GetPetByIdPath'
    query?(node: OperationNode, param: ParameterNode): string    // → 'FindPetsByStatusQuery'
    headers?(node: OperationNode, param: ParameterNode): string  // → 'DeletePetHeaders'
  }
  response?: {
    status?(node: OperationNode, statusCode: StatusCode): string // → 'ListPetsStatus200'
    options?(node: OperationNode): string                        // → 'ListPetsOptions'
    responses?(node: OperationNode): string                      // → 'ListPetsResponses'
    response?(node: OperationNode): string                       // → 'ListPetsResponse'
    body?(node: OperationNode): string                           // → 'CreatePetBody'
  }
  enum?: {
    keyName?(node: { name?: string | null }, enumTypeSuffix?: string): string // → 'PetStatusKey'
  }
}

printer

Replaces the node handler for a schema type such as 'integer' or 'date' with one that builds its TypeScript AST node. Use this.transform to recurse into nested nodes and this.options to read printer options. The printer guide covers the handler context and how overrides compose with macros.


Type	`{ nodes?: PrinterTsNodes }`
Required	`false`

See Map schema types for an example.