@kubb/plugin-react-query
Create hooks based on an operation.
Installation
bun add @kubb/plugin-react-query
pnpm add @kubb/plugin-react-query
npm install @kubb/plugin-react-query
yarn add @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.
Type: | 'all' | 'named' | 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 |
Installation
bun add @kubb/plugin-react-query
pnpm add @kubb/plugin-react-query
npm install @kubb/plugin-react-query
yarn add @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.
Type: | 'all' | 'named' | 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' |
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/client' |
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.
export async function getPetById<TData>(
petId: GetPetByIdPathParams,
): Promise<ResponseConfig<TData>["data"]> {
...
}
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.
export async function deletePet(
{
petId,
headers,
}: {
petId: DeletePetPathParams['petId']
headers?: DeletePetHeaderParams
},
config: Partial<RequestConfig> = {},
) {
...
}
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.
export async function getPetById (
{ petId }: GetPetByIdPathParams,
) {
...
}
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 |
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 |
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 |
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 |
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<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: {},
}),
],
})