@kubb/plugin-ts

Generate TypeScript types from your OpenAPI schema.

Installation

bun

bun add -d @kubb/plugin-ts

pnpm

pnpm add -D @kubb/plugin-ts

npm

npm install --save-dev @kubb/plugin-ts

yarn

yarn add -D @kubb/plugin-ts

Options

output

Specify the export location for the files and define the behavior of the output.

output.path

Path to the output folder or file that contains the generated code.

TIP

if output.path is a file, group cannot be used.

Type:	string
Required:	true
Default:	'types'

output.barrelType

Specify what to export and optionally disable barrel file generation.

TIP

Using propagate will prevent a plugin from creating a barrel file, but it will still propagate, allowing output.barrelType to export the specific function or type.

Type:	'all' | 'named' | 'propagate' | false
Required:	false
Default:	'named'

all

export * from "./gen/petService.ts"

named

export { PetService } from "./gen/petService.ts"

propagate

false

output.banner

Add a banner comment at the top of every generated file.

Type:	string | (oas: Oas) => string
Required:	false

output.footer

Add a footer text at the end of every file.

Type:	string | (oas: Oas) => string
Required:	false

output.override

Whether Kubb overrides existing external files that can be generated if they already exist.

Type:	boolean
Required:	false
Default:	false

contentType

Define which content type to use.

By default, Kubb uses the first JSON-valid media type.

Type:	'application/json' | (string & {})
Required:	false

group

Grouping combines files in a folder based on a specific type.

For example, with this configuration:

kubb.config.ts

group: {
  type: 'tag',
  name({ group }){
    return `${group}Controller`
  }
}

This generates the following structure:

.
├── src/
│   └── petController/
│   │   ├── addPet.ts
│   │   └── getPet.ts
│   └── storeController/
│       ├── createStore.ts
│       └── getStoreById.ts
├── petStore.yaml
├── kubb.config.ts
└── package.json

group.type

Specify the property to group files by. Required when group is defined.

Type:	'tag'
Required:	true*

NOTE

Required: true* means this is required only when the group option is used. The group option itself is optional.

• 'tag': Uses the first tag from operation.getTags().at(0)?.name

group.name

Return the name of a group based on the group name, this will be used for the file and name generation.

Type:	(context: GroupContext) => string
Required:	false
Default:	(ctx) => '${ctx.group}Controller'

enumType

Choose to use enum or as const for enums.

Type:	'enum' | 'asConst' | 'asPascalConst' | 'constEnum' | 'literal' | 'inlineLiteral'
Required:	false
Default:	'asConst'

TIP

The difference between asConst and asPascalConst is the casing of the constant variable name:

• asConst: generates a camelCase constant name (e.g., petType)
• asPascalConst: generates a PascalCase constant name (e.g., PetType)

NOTE

In Kubb v5, inlineLiteral will become the default.

'enum'

enum PetType {
  Dog = "dog",
  Cat = "cat",
}

'asConst'

const petType = {
  Dog: "dog",
  Cat: "cat",
} as const;

'asPascalConst'

const PetType = {
  Dog: "dog",
  Cat: "cat",
} as const;

'constEnum'

const enum PetType {
  Dog = "dog",
  Cat = "cat",
}

'literal'

type PetType = "dog" | "cat";

'inlineLiteral'

// Enum values are inlined directly into the type
export interface Pet {
  status?: "available" | "pending" | "sold";
}

enumTypeSuffix

Set a suffix for generated enum type aliases when enumType is asConst or asPascalConst.

Type:	string
Required:	false
Default:	'Key'

TIP

This option only affects type aliases generated for asConst and asPascalConst. It does not affect enum, constEnum, literal, or inlineLiteral.

enumTypeSuffix: 'Key'

const petStatus = {
  Available: 'available',
  Sold: 'sold',
} as const;

type PetStatusKey = typeof petStatus[keyof typeof petStatus];

enumTypeSuffix: 'Value'

const petStatus = {
  Available: 'available',
  Sold: 'sold',
} as const;

type PetStatusValue = typeof petStatus[keyof typeof petStatus];

enumSuffix

Set a suffix for the generated enums.

Type:	string
Required:	false
Default:	'enum'

enumKeyCasing

Choose the casing for enum key names.

Type:	'screamingSnakeCase' | 'snakeCase' | 'pascalCase' | 'camelCase' | 'none'
Required:	false
Default:	'none'

• 'screamingSnakeCase': ENUM_VALUE
• 'snakeCase': enum_value
• 'pascalCase': EnumValue
• 'camelCase': enumValue
• 'none': Uses the enum value as-is

dateType

Choose to use date or datetime as JavaScript Date instead of string.

Type:	'string' | 'date'
Required:	false
Default:	'string'

'string'

type Pet = {
  date: string;
};

'date'

type Pet = {
  date: Date;
};

integerType

Choose to use number or bigint for fields with int64 format.

'bigint' is accurate for values exceeding Number.MAX_SAFE_INTEGER, but note that JSON.parse() returns plain number at runtime — so 'number' may be a better fit for most projects.

Type:	'number' | 'bigint'
Required:	false
Default:	'bigint'

'bigint'

type Pet = {
  /**
   * @type integer, int64
   */
  id: bigint
};

'number'

type Pet = {
  /**
   * @type integer, int64
   */
  id: number
};

syntaxType

Switch between type or interface for creating TypeScript types. See Type vs Interface: Which Should You Use.

Type:	'type' | 'interface'
Required:	false
Default:	'type'

'type'

type Pet = {
  name: string;
};

'interface'

interface Pet {
  name: string;
}

unknownType

Which type to use when the Swagger/OpenAPI file is not providing more information.

Type:	'any' | 'unknown' | 'void'
Required:	false
Default:	'any'

'any'

type Pet = {
  name: any;
};

'unknown'

type Pet = {
  name: unknown;
};

'void'

type Pet = {
  name: void;
};

emptySchemaType

Which type to use for empty schema values.

Type:	'any' | 'unknown' | 'void'
Required:	false
Default:	unknownType

'any'

type Pet = {
  name: any;
};

'unknown'

type Pet = {
  name: unknown;
};

'void'

type Pet = {
  name: void;
};

optionalType

Choose what to use as mode for an optional value.

Type:	'questionToken' | 'undefined' | 'questionTokenAndUndefined'
Required:	false
Default:	'questionToken'

'questionToken'

type Pet = {
  type?: string;
};

'undefined'

type Pet = {
  type: string | undefined;
};

'questionTokenAndUndefined'

type Pet = {
  type?: string | undefined;
};

arrayType

Choose between Array<Type> or Type[] syntax for array types.

Type:	'array' | 'generic'
Required:	false
Default:	'array'

'array'

type Pet = {
  tags: string[];
};

'generic'

type Pet = {
  tags: Array<string>;
};

paramsCasing

Transform parameter names to a specific casing format for path, query, and header parameters.

IMPORTANT

When enabled, this option transforms property names in PathParams, QueryParams, and HeaderParams types to the specified casing. Response and request body types are not affected.

All plugins that reference parameters (like @kubb/plugin-client, @kubb/plugin-react-query, @kubb/plugin-swr, @kubb/plugin-faker, @kubb/plugin-mcp) should use the same paramsCasing setting to ensure type compatibility.

Type:	'camelcase'
Required:	false
Default:	undefined

Original API

// OpenAPI spec has: step_id, X-Custom-Header, bool_param

// Without paramsCasing
type FindPetsByStatusPathParams = {
  step_id: string;
};

type FindPetsByStatusQueryParams = {
  bool_param?: boolean;
};

type FindPetsByStatusHeaderParams = {
  "X-Custom-Header"?: string;
};

With paramsCasing: 'camelcase'

// Properties are transformed to camelCase

type FindPetsByStatusPathParams = {
  stepId: string;  // ✓ camelCase
};

type FindPetsByStatusQueryParams = {
  boolParam?: boolean;  // ✓ camelCase
};

type FindPetsByStatusHeaderParams = {
  xCustomHeader?: string;  // ✓ camelCase
};

include

Array containing include parameters to include tags, operations, methods, paths, or content types.

Type:	Array<Include>
Required:	false

Include

export type Include = {
  type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType'
  pattern: string | RegExp
}

exclude

Array containing exclude parameters to exclude or skip tags, operations, methods, paths, or content types.

Type:	Array<Exclude>
Required:	false

Exclude

export type Exclude = {
  type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType'
  pattern: string | RegExp
}

override

Array containing override parameters to override options based on tags, operations, methods, paths, or content types.

Type:	Array<Override>
Required:	false

Override

export type Override = {
  type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType'
  pattern: string | RegExp
  options: PluginOptions
}

generators

See Generators for more information on how to use generators.

Type:	Array<Generator<PluginTs>>
Required:	false

transformers

transformers.name

Customize the names based on the type that is provided by the plugin.

Type:	(name: string, type?: ResolveType) => string
Required:	false

type ResolveType = "file" | "function" | "type" | "const";

Example

import { defineConfig } from "@kubb/core";
import { pluginOas } from "@kubb/plugin-oas";
import { pluginTs } from "@kubb/plugin-ts";

export default defineConfig({
  input: {
    path: "./petStore.yaml",
  },
  output: {
    path: "./src/gen",
  },
  plugins: [
    pluginOas(),
    pluginTs({
      output: {
        path: "./types",
      },
      exclude: [
        {
          type: "tag",
          pattern: "store",
        },
      ],
      group: {
        type: "tag",
        name: ({ group }) => `${group}Controller`,
      },
      enumType: "asConst",
      enumTypeSuffix: "Value",
      enumSuffix: "Enum",
      dateType: "date",
      unknownType: "unknown",
      optionalType: "questionTokenAndUndefined",
      paramsCasing: "camelcase", // Transform param names to camelCase
    }),
  ],
});

See Also

• TypeScript
• TypeScript Compiler API