@kubb/plugin-swr
With the SWR plugin you can create SWR hooks based on an operation.
Installation
bun add @kubb/plugin-swr
pnpm add @kubb/plugin-swr
npm install @kubb/plugin-swr
yarn add @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 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.
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 |
mutation.importPath
Type: | string |
---|---|
Required: | false |
Default: | 'swr/mutation' |
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.
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<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'
export default defineConfig({
input: {
path: './petStore.yaml',
},
output: {
path: './src/gen',
},
plugins: [
pluginOas(),
pluginTs(),
pluginSwr({
output: {
path: './hooks',
},
group: {
type: 'tag',
name: ({ group }) => `${group}Hooks`,
},
client: {
dataReturnType: 'full',
},
parser: 'zod',
}),
],
})