Skip to content
SWR logo

SWR

Officialv5.9.4

@kubb/plugin-swr

kubb add plugin-swr

Options

Pass these options to pluginSwr(). Shared options link to Shared plugin options.

Options overview

OptionPurposeDefault
clientWhich registered client plugin the hooks call.Auto-detected
returnTypeWhat the hooks resolve to.'data'
queryWhich methods become useSWR hooks, and the import.{ methods: ['GET', 'QUERY'], importPath: 'swr' }
queryKeyBuild the SWR key of each query.queryKeyTransformer
mutationWhich methods become useSWRMutation hooks, and the import.{ methods: ['POST', 'PUT', 'PATCH', 'DELETE'], importPath: 'swr/mutation' }
mutationKeyBuild the SWR key of each mutation.mutationKeyTransformer
outputWhere files are written.{ path: 'hooks', barrel: { type: 'named' } }
groupSplit output by tag or path.None
includeKeep only operations that match.None
excludeSkip operations that match.[]
overrideApply different options per pattern.[]
resolverCustomize generated names and file paths.resolverSwr
macrosRewrite AST nodes before printing.[]
The plugin always generates hooks, so it has no hooks option. It does not generate useSWRInfinite or suspense hooks.

Option details

client

The registered client plugin whose functions the hooks call. A lone client plugin is detected, so set client only when several are registered. Generation fails when none is registered.

Type'fetch' | 'axios' | 'client'
Requiredfalse
'fetch'
Calls @kubb/plugin-fetch functions.
'axios'
Calls @kubb/plugin-axios functions.
'client'
Calls @kubb/plugin-client functions. Your client module must also export the RequestConfig and ResponseErrorConfig types.

returnType

What the hooks resolve to.

Type'data' | 'full'
Requiredfalse
Default'data'
'data'
Default. Resolves to the success body.
'full'
Resolves to the client's whole RequestResult, so a hook can read the status and response headers. Needs a client plugin with returnType'full' or 'plain', or generation stops with an error.
pluginSwr({ returnType: 'full' })

// with integerType: 'number' on the adapter
const { data: result } = useGetPetById({ path: { petId: 1 } })
const etag = result?.response.headers.get('ETag')

query

Which operations become useSWR hooks and where useSWR is imported from. false skips query output.

TypePartial<Query> | false
Requiredfalse
Default{ methods: ['GET', 'QUERY'], importPath: 'swr' }

query.methods

HTTP methods treated as queries. A method in neither query.methods nor mutation.methods gets no hook, so keep 'QUERY' when you replace the list.

TypeArray<string>
Requiredfalse
Default['GET', 'QUERY']

query.importPath

Module of the default useSWR import, written as import useSWR from '<importPath>'. A relative path resolves from the generated file.

Typestring
Requiredfalse
Default'swr'

queryKey

Builds each query's SWR key from the operation node and variant: 'query'. The default key is [{ url, params }, query, body], with only the parts the operation has.

Type(props: { node, casing, variant }) => Array<unknown>
Requiredfalse
DefaultqueryKeyTransformer
Returned strings are copied into the generated code as written. Wrap a string literal in JSON.stringify(...).

To extend the default, spread it. Single entries can change between releases. See SWR keys.

import { queryKeyTransformer } from '@kubb/plugin-swr'

queryKey: (props) => [JSON.stringify('v2'), ...queryKeyTransformer(props)]

mutation

Which operations become useSWRMutation hooks and where useSWRMutation is imported from. false skips mutation output.

TypePartial<Mutation> | false
Requiredfalse
Default{ methods: ['POST', 'PUT', 'PATCH', 'DELETE'], importPath: 'swr/mutation' }

mutation.methods

HTTP methods treated as mutations. A method also in query.methods stays a query.

TypeArray<string>
Requiredfalse
Default['POST', 'PUT', 'PATCH', 'DELETE']

mutation.importPath

Module of the default useSWRMutation import, written as import useSWRMutation from '<importPath>'. A relative path resolves from the generated file.

Typestring
Requiredfalse
Default'swr/mutation'

mutationKey

Builds each mutation's SWR key, for matching keys in SWR's global mutate. It takes the same props as queryKey with variant: 'mutation', and copies strings the same way. The default key is [{ url }].

Type(props: { node, casing, variant }) => Array<unknown>
Requiredfalse
DefaultmutationKeyTransformer
import { mutationKeyTransformer } from '@kubb/plugin-swr'

mutationKey: (props) => [JSON.stringify('v2'), ...mutationKeyTransformer(props)]

resolver

Overrides generated file and symbol names. Members you leave out keep resolverSwr. See resolver for the shared name, file, and imports members.

TypeResolverPatch<ResolverSwr>
Requiredfalse
Partial override
type ResolverSwrPatch = {
  // plus the shared name, file, and imports members
  query?: {
    name?(node: OperationNode): string // 'useGetPetById'
    optionsName?(node: OperationNode): string // 'getPetByIdQueryOptions'
    keyName?(node: OperationNode): string // 'getPetByIdQueryKey'
    keyTypeName?(node: OperationNode): string // 'GetPetByIdQueryKey'
  }
  mutation?: {
    name?(node: OperationNode): string // 'useUpdatePet'
    keyName?(node: OperationNode): string // 'updatePetMutationKey'
    keyTypeName?(node: OperationNode): string // 'UpdatePetMutationKey'
    argTypeName?(node: OperationNode): string // 'UpdatePetMutationArg'
  }
}