Skip to content

@kubb/plugin-ts ​

Generate TypeScript types from your OpenAPI schema.

Installation ​

shell
bun add -d @kubb/plugin-ts
shell
pnpm add -D @kubb/plugin-ts
shell
npm install --save-dev @kubb/plugin-ts
shell
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'
typescript
export * from "./gen/petService.ts"
typescript
export { PetService } from "./gen/petService.ts"
typescript
typescript

output.banner ​

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

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

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

typescript
enum PetType {
  Dog = "dog",
  Cat = "cat",
}
typescript
const petType = {
  Dog: "dog",
  Cat: "cat",
} as const;
typescript
const PetType = {
  Dog: "dog",
  Cat: "cat",
} as const;
typescript
const enum PetType {
  Dog = "dog",
  Cat = "cat",
}
typescript
type PetType = "dog" | "cat";
typescript
// 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.

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

type PetStatusKey = typeof petStatus[keyof typeof petStatus];
typescript
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'
typescript
type Pet = {
  date: string;
};
typescript
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'
typescript
type Pet = {
  /**
   * @type integer, int64
   */
  id: bigint
};
typescript
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'
typescript
type Pet = {
  name: string;
};
typescript
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'
typescript
type Pet = {
  name: any;
};
typescript
type Pet = {
  name: unknown;
};
typescript
type Pet = {
  name: void;
};

emptySchemaType ​

Which type to use for empty schema values.

Type:'any' | 'unknown' | 'void'
Required:false
Default:unknownType
typescript
type Pet = {
  name: any;
};
typescript
type Pet = {
  name: unknown;
};
typescript
type Pet = {
  name: void;
};

optionalType ​

Choose what to use as mode for an optional value.

Type:'questionToken' | 'undefined' | 'questionTokenAndUndefined'
Required:false
Default:'questionToken'
typescript
type Pet = {
  type?: string;
};
typescript
type Pet = {
  type: string | undefined;
};
typescript
type Pet = {
  type?: string | undefined;
};

arrayType ​

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

Type:'array' | 'generic'
Required:false
Default:'array'
typescript
type Pet = {
  tags: string[];
};
typescript
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
typescript
// 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;
};
typescript
// 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
typescript
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
typescript
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
typescript
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
typescript
type ResolveType = "file" | "function" | "type" | "const";

Example ​

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

Released under the MIT License.