Skip to content

@kubb/plugin-ts

With the TypeScript plugin you can create TypeScript types.

Installation

shell
bun add @kubb/plugin-ts
shell
pnpm add @kubb/plugin-ts
shell
npm install @kubb/plugin-ts
shell
yarn add @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 will contain the generated code.

TIP

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

Type:string
Required:true
Default:'types'

output.barrelType

Define what needs to be exported, here you can also disable the export of barrel files.

Type:'all' | 'named' | false
Required:false
Default:'named'
typescript
export * from "./gen/petService.ts"
typescript
export { PetService } from "./gen/petService.ts"
typescript

output.banner

Add a banner text in the beginning of every file.

Type:string
Required:false

Add a footer text at the end of every file.

Type:string
Required:false

group

Grouping makes it possible to combine files in a folder based on specific type.

Imagine you have the following setup:

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

That will create a structure like this:

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

group.type

Define a type where to group the files on.

Type:'tag'
Required:true
  • 'tag': Use of 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'
Required:false
Default:'asConst'
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'

enumSuffix

Set a suffix for the generated enums.

Type:string
Required:false
Default:''

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
}

unknownType

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

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

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
}

oasType

Export an Oas object as Oas type with import type { Infer } from '@kubb/plugin-ts/oas'
See infer in how to use the types with @kubb/plugin-ts/oas.

Type:'infer' | false
Required:false

include

Array containing include parameters to include tags/operations/methods/paths.

Type:Array<Include>
Required:false
Include
typescript
export type Include = {
  type: 'tag' | 'operationId' | 'path' | 'method'
  pattern: string | RegExp
}

exclude

Array containing exclude parameters to exclude/skip tags/operations/methods/paths.

Type:Array<Exclude>
Required:false
Exclude
typescript
export type Exclude = {
  type: 'tag' | 'operationId' | 'path' | 'method'
  pattern: string | RegExp
}

override

Array containing override parameters to override options based on tags/operations/methods/paths.

Type:Array<Override>
Required:false
Override
typescript
export type Override = {
  type: 'tag' | 'operationId' | 'path' | 'method'
  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",
enumSuffix
: 'Enum',
dateType
: 'date',
unknownType
: 'unknown',
optionalType
: 'questionTokenAndUndefined',
oasType
: false,
}), ], })

Released under the MIT License.