@kubb/plugin-ts
With the TypeScript plugin you can create TypeScript types.
Installation
bun add @kubb/plugin-ts
pnpm add @kubb/plugin-ts
npm install @kubb/plugin-ts
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.
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' |
export * from "./gen/petService.ts"
export { PetService } from "./gen/petService.ts"
output.banner
Add a banner text in the beginning of every file.
Type: | string |
---|---|
Required: | false |
output.footer
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:
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' |
enum PetType {
Dog = 'dog',
Cat = 'cat',
}
const petType = {
Dog: 'dog',
Cat: 'cat',
} as const
const PetType = {
Dog: 'dog',
Cat: 'cat',
} as const
const enum PetType {
Dog = 'dog',
Cat = 'cat',
}
type PetType = 'dog' | 'cat'
enumSuffix
Set a suffix for the generated enums.
Type: | string |
---|---|
Required: | false |
Default: | 'enum' |
dateType
Choose to use date
or datetime
as JavaScript Date
instead of string
.
Type: | 'string' | 'date' |
---|---|
Required: | false |
Default: | 'string' |
type Pet = {
date: string
}
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' |
type Pet = {
name: any
}
type Pet = {
name: unknown
}
optionalType
Choose what to use as mode for an optional value.
Type: | 'questionToken' | 'undefined' | 'questionTokenAndUndefined' |
---|---|
Required: | false |
Default: | 'questionToken' |
type Pet = {
type?: string
}
type Pet = {
type: string | undefined
}
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 |
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 |
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 |
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 |
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",
enumSuffix: 'Enum',
dateType: 'date',
unknownType: 'unknown',
optionalType: 'questionTokenAndUndefined',
oasType: false,
}),
],
})