@kubb/plugin-swr

Generate SWR hooks from your OpenAPI schema.

Installation

bun

bun add -d @kubb/plugin-swr

pnpm

pnpm add -D @kubb/plugin-swr

npm

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

yarn

yarn add -D @kubb/plugin-swr

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

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 comment at the end of every generated 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.

Type:	'tag'
Required:	true

• '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'

client

client.importPath

Path to the client used for API calls. Supports both relative and absolute paths.

When to use importPath

Use importPath when you want to:

• Customize the HTTP client: Provide your own client implementation with custom configurations (e.g., baseURL, headers, interceptors)
• Add authentication: Include authentication tokens or other security mechanisms in your client
• Override default behavior: Replace the default Kubb client with your own implementation

Default behavior

When importPath is not specified:

• If bundle: false (default): Uses @kubb/plugin-client/clients/${client} where client is either axios or fetch
• If bundle: true: Bundles the client into .kubb/fetch.ts

Import structure

Generated code imports:

• Client as default import
• Types as named type imports

Example for axios client:

/**
 * Generated by Kubb (https://kubb.dev/).
 * Do not edit manually.
 */
import client from '${client.importPath}'
import type { RequestConfig, ResponseErrorConfig } from '${client.importPath}'
// ... rest of generated file

IMPORTANT

When using importPath with query plugins such as @kubb/plugin-react-query, @kubb/plugin-vue-query, @kubb/plugin-svelte-query, @kubb/plugin-solid-query, or @kubb/plugin-swr, the generated hooks also import type Client from the custom module:

import type { Client, RequestConfig, ResponseErrorConfig } from '@/lib/client'

Your custom client module must export these three types. If any of them is missing, TypeScript will report an unresolvable import error.

client.ts

export type RequestConfig<TData = unknown> = {
  url?: string
  method: 'GET' | 'PUT' | 'PATCH' | 'POST' | 'DELETE'
  params?: object
  data?: TData | FormData
  responseType?: 'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream'
  signal?: AbortSignal
  headers?: HeadersInit
}

export type ResponseConfig<TData = unknown> = {
  data: TData
  status: number
  statusText: string
}

export type ResponseErrorConfig<TError = unknown> = TError

// The Client type alias is required when using query plugins
export type Client = <TData, _TError = unknown, TVariables = unknown>(
  config: RequestConfig<TVariables>
) => Promise<ResponseConfig<TData>>

export const client: Client = async (config) => { /* ... */ }
export default client

Example configuration with custom client:

import { defineConfig } from '@kubb/core'
import { pluginClient } from '@kubb/plugin-client'

export default defineConfig({
  // ...
  plugins: [
    pluginClient({
      importPath: './src/client.ts' // Path to your custom client
    }),
  ],
})

TIP

Learn more about defining a custom client here.

Type:	string
Required:	false

client.dataReturnType

Return type used when calling the client.

Type:	'data' | 'full'
Required:	false
Default:	'data'

• 'data' returns ResponseConfig[data].
• 'full' returns ResponseConfig.

'data'

export async function getPetById<TData>(
  petId: GetPetByIdPathParams,
): Promise<ResponseConfig<TData>["data"]> {
  ...
}

'full'

export async function getPetById<TData>(
  petId: GetPetByIdPathParams,
): Promise<ResponseConfig<TData>> {
  ...
}

client.baseURL

Sets a custom base URL for all generated calls.

Type:	string
Required:	false

client.clientType

Specify whether to use function-based or class-based clients.

Type:	'function' | 'class'
Required:	false
Default:	'function'

WARNING

This plugin is only compatible with clientType: 'function' (the default). If clientType: 'class' is detected, the plugin will automatically generate its own inline function-based client instead of importing from @kubb/plugin-client.

client.bundle

Controls whether the HTTP client runtime is copied into the generated .kubb directory.

Type:	boolean
Required:	false
Default:	false

• true adds a .kubb/fetch.ts file containing the selected client template (fetch or axios). Generated clients remain self-contained.
• false keeps generated clients slim by importing the shared runtime from @kubb/plugin-client/clients/{client}.
• Override this behavior by providing a custom client.importPath.

paramsType

Defines how parameters are passed to generated functions. 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' returns params and pathParams as an object.
• 'inline' returns params as comma-separated params.

'object'

export async function deletePet(
  {
    petId,
    headers,
  }: {
    petId: DeletePetPathParams['petId']
    headers?: DeletePetHeaderParams
  },
  config: Partial<RequestConfig> = {},
) {
...
}

'inline'

export async function deletePet(
  petId: DeletePetPathParams['petId'],
  headers?: DeletePetHeaderParams,
  config: Partial<RequestConfig> = {}
){
  ...
}

paramsCasing

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

IMPORTANT

When using paramsCasing, ensure that @kubb/plugin-ts also has the same paramsCasing setting. This option automatically maps transformed parameter names back to their original API names in HTTP requests.

Type:	'camelcase'
Required:	false
Default:	undefined

• 'camelcase' transforms parameter names to camelCase

With paramsCasing: 'camelcase'

// Function parameters use camelCase
export async function deletePet(
  petId: DeletePetPathParams['petId'],  // ✓ camelCase
  headers?: DeletePetHeaderParams,
  config: Partial<RequestConfig> = {}
) {
  // Automatically maps back to original name for the API
  const pet_id = petId
  
  return fetch({
    method: 'DELETE',
    url: `/pet/${pet_id}`,  // Uses original API parameter name
    ...
  })
}

Without paramsCasing

// Parameters use original API naming
export async function deletePet(
  pet_id: DeletePetPathParams['pet_id'],  // Original naming
  headers?: DeletePetHeaderParams,
  config: Partial<RequestConfig> = {}
) {
  return fetch({
    method: 'DELETE',
    url: `/pet/${pet_id}`,
    ...
  })
}

TIP

The client automatically generates mapping code to convert camelCase parameter names back to the original API format. You write code with developer-friendly camelCase names, but HTTP requests use the exact parameter names from your OpenAPI specification.

pathParamsType

Defines how pathParams are passed to generated functions.

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

• 'object' returns pathParams as an object.
• 'inline' returns pathParams as comma-separated params.

'object'

export async function getPetById (
  { petId }: GetPetByIdPathParams,
) {
  ...
}

'inline'

export async function getPetById(
  petId: GetPetByIdPathParams,
) {
  ...
}

parser

Parser used before returning data.

Type:	'client' | 'zod'
Required:	false
Default:	'client'

• 'zod' uses @kubb/plugin-zod to parse data.
• 'client' returns data without parsing.

queryKey

Customize the queryKey.

WARNING

When using a string you need to use JSON.stringify.

Type:	(props: { operation: Operation; schemas: OperationSchemas }) => unknown[]
Required:	false

query

query.methods

Type:	Array<HttpMethod>
Required:	false

query.importPath

Type:	string
Required:	false
Default:	'swr'

mutation

mutation.methods

Type:	Array<HttpMethod>
Required:	false
Default:	['post', 'put', 'delete']

mutation.importPath

Type:	string
Required:	false
Default:	'swr/mutation'

mutation.paramsToTrigger

When true, mutation parameters (path params, query params, headers, request body) are passed via trigger() instead of as hook arguments. This aligns with React Query's mutation pattern where variables are passed when triggering the mutation.

WARNING

This will become the default behavior in v5. Set mutation.paramsToTrigger: true to opt-in early.

Type:	boolean
Required:	false
Default:	false

Example with paramsToTrigger: false (default):

// Parameters required when calling the hook
const { trigger } = useDeletePet(petId, params, headers)
trigger()

Example with paramsToTrigger: true:

// Parameters passed when triggering
const { trigger } = useDeletePet()
trigger({ petId, data, params, headers })

mutationKey

Customize the mutationKey.

WARNING

When using a string you need to use JSON.stringify.

Type:	(props: { operation: Operation; schemas: OperationSchemas }) => unknown[]
Required:	false

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<PluginSwr>>
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 { pluginSwr } from '@kubb/plugin-swr'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginZod } from '@kubb/plugin-zod'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    pluginOas(),
    pluginTs(),
    pluginZod(),
    pluginSwr({
      output: {
        path: './hooks',
      },
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Hooks`,
      },
      client: {
        dataReturnType: 'full',
      },
      parser: 'zod',
    }),
  ],
})

See Also

• SWR