@kubb/plugin-react-query

Create hooks based on an operation.

Installation

bun

bun add -d @kubb/plugin-react-query

pnpm

pnpm add -D @kubb/plugin-react-query

npm

npm install --save-dev @kubb/plugin-react-query

yarn

yarn add -D @kubb/plugin-react-query

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

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'

all

export * from "./gen/petService.ts"

named

export { PetService } from "./gen/petService.ts"

propagate

false

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

Installation

bun

bun add -d @kubb/plugin-react-query

pnpm

pnpm add -D @kubb/plugin-react-query

npm

npm install --save-dev @kubb/plugin-react-query

yarn

yarn add -D @kubb/plugin-react-query

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

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'

all

export * from "./gen/petService.ts"

named

export { PetService } from "./gen/petService.ts"

propagate

false

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'

client

client.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/clients/axios'

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

'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

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

Type:	string
Required:	false

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.

'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

How to style your params, by default no casing is applied.

Type:	'camelcase'
Required:	false
Default:	``

• 'camelcase' will use camelcase for the params names

'camelcase'

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

''

export async function deletePet(
  pet_id: DeletePetPathParams['pet_id'],
  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.

'object'

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

'inline'

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.

infinite

When set, an 'infiniteQuery' hook will be added.
To disable infinite queries pass false.

Type:	Infinite | false
Required:	false
Default:	false

Infinite

type Infinite = {
  /**
   * Specify the params key used for `pageParam`.
   * @default `'id'`
   */
  queryParam: string
  /**
   * Which field of the data will be used, set it to undefined when no cursor is known.
   */
  cursorParam: string | undefined
  /**
   * The initial value, the value of the first page.
   * @default `0`
   */
  initialPageParam: unknown
} | false

infinite.queryParam

Specify the params key used for pageParam.

Type:	string
Required:	false
Default:	'id'

infinite.initialPageParam

Specify the initial page param value.

Type:	unknown
Required:	false
Default:	0

infinite.cursorParam

Which field of the data will be used, set it to undefined when no cursor is known.

Type:	string | undefined
Required:	false

query

Override some useQuery behaviours.
To disable queries pass false.

Type:	Query
Required:	false

Query

type Query = {
  methods: Array<HttpMethod>
  importPath?: string
} | false

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

Define which HttpMethods can be used for queries

Type:	Array<HttpMethod>
Required:	['get']

query.importPath

Path to the useQuery that will be used to do the useQuery functionality. It will be used as import { useQuery } from '${hook.importPath}'. It allows both relative and absolute path. the path will be applied as is, so relative path should be based on the file being generated.

Type:	string
Required:	false
Default:	'@tanstack/react-query'

suspense

When set, a suspenseQuery hook will be added. This will only work for v5 and react.

Type:	object | false
Required:	false

mutation

Override some useMutation behaviours.
To disable queries pass false.

Type:	Mutation
Required:	false

Query

type Mutation = {
  methods: Array<HttpMethod>
  importPath?: string
} | false

mutationKey

Customize the mutationKey.

WARNING

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

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

mutation.methods

Define which HttpMethods can be used for mutations

Type:	Array<HttpMethod>
Required:	['get']

mutation.importPath

Path to the useQuery that will be used to do the useQuery functionality. It will be used as import { useMutation } from '${hook.importPath}'. It allows both relative and absolute path. the path will be applied as is, so relative path should be based on the file being generated.

Type:	string
Required:	false
Default:	'@tanstack/react-query'

include

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

Type:	Array<Include>
Required:	false

Include

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

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

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<PluginReactQuery>>
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 { pluginReactQuery } from '@kubb/plugin-react-query'
import { pluginTs } from '@kubb/plugin-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    pluginOas(),
    pluginTs(),
    pluginReactQuery({
      output: {
        path: './hooks',
      },
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Hooks`,
      },
      client: {
        dataReturnType: 'full',
      },
      mutation: {
        methods: [ 'post', 'put', 'delete' ],
      },
      infinite: {
        queryParam: 'next_page',
        initialPageParam: 0,
        cursorParam: 'nextCursor',
      },
      query: {
        methods: [ 'get' ],
        importPath: "@tanstack/react-query"
      },
      suspense: {},
    }),
  ],
})

Links

• Tanstack Query