Skip to content

@kubb/plugin-client

The Client plugin enables you to generate API controllers, simplifying the process of handling API requests and improving integration between frontend and backend services.

By default, we are using Axios but you can also add your own client, see Use of Fetch.

Installation

shell
bun add @kubb/plugin-client
shell
pnpm add @kubb/plugin-client
shell
npm install @kubb/plugin-client
shell
yarn add @kubb/plugin-client

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:'clients'

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'

importPath

Path to the client import path that will be used to do the API calls.
It will be used as import client from '${client.importPath}'.
It allows both relative and absolute path but be aware that we will not change the path.

TIP

Use of default exports as export default client = ()=>{}

Type:string
Required:false
Default:'@kubb/plugin-client/client'

operations

Create operations.ts file with all operations grouped by methods.

Type:boolean
Required:false
Default:false

dataReturnType

ReturnType that will be used when calling the client.

Type:'data' | 'full'
Required:false
Default:'data'
  • 'data' will return ResponseConfig[data].
  • 'full' will return ResponseConfig.
typescript
export async function getPetById<TData>(
  petId: GetPetByIdPathParams,
): Promise<ResponseConfig<TData>["data"]> {
  ...
}
typescript
export async function getPetById<TData>(
  petId: GetPetByIdPathParams,
): Promise<ResponseConfig<TData>> {
  ...
}

paramsType

How to pass your params. Here you can switch between object-style parameters and inline parameters.

Type:'object' | 'inline'
Required:false
Default:'inline'

TIP

When paramsType is set to 'object', pathParams will also be set to 'object'.

  • 'object' will return the params and pathParams as an object.
  • 'inline' will return the params as comma separated params.
typescript
export async function deletePet(
  {
    petId,
    headers,
  }: {
    petId: DeletePetPathParams['petId']
    headers?: DeletePetHeaderParams
  },
  config: Partial<RequestConfig> = {},
) {
...
}
typescript
export async function deletePet(
  petId: DeletePetPathParams['petId'],
  headers?: DeletePetHeaderParams,
  config: Partial<RequestConfig> = {}
){
  ...
}

pathParamsType

How to pass your pathParams.

Type:'object' | 'inline'
Required:false
Default:'inline'
  • 'object' will return the pathParams as an object.
  • 'inline' will return the pathParams as comma separated params.
typescript
export async function getPetById (
  { petId }: GetPetByIdPathParams,
) {
  ...
}
typescript
export async function getPetById(
  petId: GetPetByIdPathParams,
) {
  ...
}

parser

Which parser should be used before returning the data.

Type:'client' | 'zod'
Required:false
Default:'client'
  • 'zod' will use @kubb/plugin-zod to parse the data.
  • 'client' will return without parsing the data.

baseURL

Allows you to set a custom base url for all generated calls.

Type:string
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<PluginClient>>
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

kubb.config.ts
typescript
import { 
defineConfig
} from '@kubb/core'
import {
pluginOas
} from '@kubb/plugin-oas'
import {
pluginTs
} from '@kubb/plugin-ts'
import {
pluginClient
} from '@kubb/plugin-client'
export default
defineConfig
({
input
: {
path
: './petStore.yaml',
},
output
: {
path
: './src/gen',
},
plugins
: [
pluginOas
(),
pluginTs
(),
pluginClient
({
output
: {
path
: './clients/axios',
barrelType
: 'named',
banner
: '/* eslint-disable no-alert, no-console */',
footer
: ''
},
group
: {
type
: 'tag',
name
: ({
group
}) => `${
group
}Service`,
},
transformers
: {
name
: (
name
,
type
) => {
return `${
name
}Client`
}, },
operations
: true,
parser
: 'client',
exclude
: [
{
type
: 'tag',
pattern
: 'store',
}, ],
pathParamsType
: "object",
dataReturnType
: 'full',
}), ], })

Released under the MIT License.