Reference

Options

Configuration options for @kubb/plugin-ts.

Pass these options to pluginTs(). Shared options link to Shared plugin options, which documents their behavior once.

Options overview

Option	Purpose	Default
`output`	Where the generated files are written and exported.	`{ path: 'types', barrel: { type: 'named' } }`
↳ `output.path`	Choose the output folder or file.	`'types'`
↳ `output.mode`	Write a single file or a directory of files.	Inferred from `output.path`
↳ `output.barrel`	Configure barrel exports.	`{ type: 'named' }`
↳ `output.banner`	Add content before generated code.	None
↳ `output.footer`	Add content after generated code.	None
`group`	Split output into per-tag or per-path folders.	None
↳ `group.type`	Group operations by tag or URL path.	Required with `group`
↳ `group.name`	Customize output group names.	camelCased tag or raw path segment
`enum`	How enums are generated and cased.	`{ type: 'asConst', constCasing: 'camelCase', typeSuffix: 'Key', keyCasing: 'none' }`
↳ `enum.type`	Choose how enums are generated.	`'asConst'`
↳ `enum.constCasing`	Set the casing of enum constants.	`'camelCase'`
↳ `enum.typeSuffix`	Set the companion type suffix.	`'Key'`
↳ `enum.keyCasing`	Set the casing of enum keys.	`'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
↳ `printer.nodes`	Customize handlers for schema node types.	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'

Default value. Emits an as const object plus a key/value type. Tree-shakeable, with no runtime.

'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 const 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'

Default value. 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'

Default value. 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'

Default value. 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'

Default value. 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, the strictest form. Use it with "exactOptionalPropertyTypes": true.

arrayType

Syntax for array types.


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

'array'

Default value. 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 = {
  name?(name: string): string
  file?: {
    baseName?(params: { name: string; extname: string }): string
    path?(params: { baseName: string; output: Output }): string
  }
  imports?(options: ResolveImportsOptions): Array<ImportNode>
  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`

Map date schemas to the Date object

import ts from 'typescript'
import { pluginTs } from '@kubb/plugin-ts'

pluginTs({
  printer: {
    nodes: {
      date() {
        return ts.factory.createTypeReferenceNode('Date', [])
      },
      integer() {
        return ts.factory.createKeywordTypeNode(ts.SyntaxKind.BigIntKeyword)
      },
    },
  },
})

Customize generated types