Skip to content

@kubb/swagger-tanstack-query 🦙

TIP


Tanstack/query v5 is fully supported, see Migrating to TanStack Query v5.

Just install v5 in your project and Kubb will check the package.json to see if you are using v4 or v5.

With the Swagger Tanstack Query plugin you can create:

  • react-query hooks based on an operation in the Swagger file.
  • solid-query primitives based on an operation in the Swagger file.
  • svelte-query primitives based on an operation in the Swagger file.
  • vue-query hooks based on an operation in the Swagger file.

Installation

shell
bun add @kubb/swagger-tanstack-query @kubb/swagger-ts  @kubb/swagger @kubb/swagger-client
shell
pnpm add @kubb/swagger-tanstack-query @kubb/swagger-ts  @kubb/swagger @kubb/swagger-client
shell
npm install @kubb/swagger-tanstack-query @kubb/swagger-ts  @kubb/swagger @kubb/swagger-client
shell
yarn add @kubb/swagger-tanstack-query @kubb/swagger-ts  @kubb/swagger @kubb/swagger-client

Options

output

output.path

Output to save the Tanstack Query hooks.

INFO

Type: string
Default: 'hooks'

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery({
      output: {
        path: './hooks',
      },
    }),
  ],
})

output.exportAs

Name to be used for the export * as from './'

INFO

Type: string

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery({
      output: {
        exportAs: 'hooks',
      },
    }),
  ],
})

output.extName

Add an extension to the generated imports and exports, default it will not use an extension

INFO

Type: string

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery({
      output: {
        extName: '.js',
      },
    }),
  ],
})

output.exportType

Define what needs to exported, here you can also disable the export of barrel files

INFO

Type: 'barrel' | 'barrelNamed' | false

group

Group the Tanstack Query hooks based on the provided name.

group.type

Tag will group based on the operation tag inside the Swagger file.

Type: 'tag'
Required: true

group.output

Relative path to save the grouped Tanstack Query hooks. {{tag}} will be replaced by the current tagName.

Type: string
Example: hooks/{{tag}}Controller => hooks/PetController
Default: '${output}/{{tag}}Controller'

group.exportAs

Name to be used for the export * as {{exportAs}} from './

Type: string
Default: '{{tag}}Hooks'

INFO

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery(
      {
        output: {
          path: './hooks',
        },
        group: { type: 'tag', output: './hooks/{{tag}}Hooks' },
      },
    ),
  ],
})

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 paths. the path will be applied as is, so the relative path should be based on the file being generated.

INFO

Type: string
Default: '@kubb/swagger-client/client'

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery(
      {
        client: {
          importPath: '../../client.ts',
        },
      },
    ),
  ],
})

dataReturnType

ReturnType that needs to be used when calling client().

'data' will return ResponseConfig[data].
'full' will return ResponseConfig.

type

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

INFO

Type: 'data' | 'full'
Default: 'data'

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery(
      {
        dataReturnType: 'data',
      },
    ),
  ],
})
typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery(
      {
        dataReturnType: 'full',
      },
    ),
  ],
})

parser

Which parser can be used before returning the data to @tanstack/query.

'zod' will use @kubb/swagger-zod to parse the data.

type

typescript
export function getPetByIdQueryOptions() {
  const queryKey = getPetByIdQueryKey(petId)
  return {
    queryKey,
    queryFn: async () => {
      const res = await client({
        method: 'get',
        url: `/pet/${petId}`,
      })

      return getPetByIdQueryResponseSchema.parse(res.data)
    },
  }
}

INFO

Type: 'zod'

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery(
      {
        parser: 'zod',
      },
    ),
  ],
})

framework

Framework to be generated for.

INFO

Type: 'react' | 'solid' | 'svelte' | 'vue'
Default: 'react'

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery(
      {
        framework: 'solid',
      },
    ),
  ],
})

infinite

When set, an 'infiniteQuery' hook will be added.

type

typescript
type Infinite = {
  /**
   * Specify the params key used for `pageParam`.
   * Used inside `useInfiniteQuery`, `createInfiniteQueries`, `createInfiniteQuery`
   * @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
}

INFO

Type: Infinite

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery({ infinite: {} }),
  ],
})

infinite.queryParam

Specify the params key used for pageParam.
Used inside useInfiniteQuery, createInfiniteQueries, createInfiniteQuery.

INFO

Type: string
Default: 'id'

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery({
      infinite: {
        queryParam: 'next_page',
      },
    }),
  ],
})

infinite.initialPageParam

Specify the initial page param value.
Used inside useInfiniteQuery, createInfiniteQueries, createInfiniteQuery and will only be needed for v5.

INFO

Type: string
Default: '0'

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery({
      infinite: {
        queryParam: 'id',
        initialPageParam: 0,
      },
    }),
  ],
})

infinite.cursorParam

Which field of the data will be used, set it to undefined when no cursor is known.
Used inside useInfiniteQuery, createInfiniteQueries, createInfiniteQuery and will only be needed for v5.

INFO

Type: string | undefined

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery({
      infinite: {
        queryParam: 'id',
        cursorParam: 'nextCursor',
      },
    }),
  ],
})

query

Override some useQuery behaviours.

type

typescript
type Query = {
  /**
   * Customize the queryKey, here you can specify a suffix.
   */
  queryKey?: (key: unknown[]) => unknown[]
}

INFO

Type: Query

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery({ query: {} }),
  ],
})

query.queryKey

Customize the queryKey, here you can specify a suffix.

WARNING

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

INFO

Type: (key: unknown[]) => unknown[]

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery({
      query: {
        queryKey: (key: string[]) => [JSON.stringify('SUFFIX'), ...key],
      },
    }),
  ],
})

suspense

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

type

typescript
type Suspense = {}

INFO

Type: Suspense

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery({ suspense: {} }),
  ],
})

include

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

type

typescript
export type Include = {
  type: 'tag' | 'operationId' | 'path' | 'method'
  pattern: string | RegExp
}

INFO

Type: Array<Include>

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery(
      {
        include: [
          {
            type: 'tag',
            pattern: 'store',
          },
        ],
      },
    ),
  ],
})

exclude

Array containing exclude parameters to exclude/skip tags/operations/methods/paths.

type

typescript
export type Exclude = {
  type: 'tag' | 'operationId' | 'path' | 'method'
  pattern: string | RegExp
}

INFO

Type: Array<Exclude>

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery(
      {
        exclude: [
          {
            type: 'tag',
            pattern: 'store',
          },
        ],
      },
    ),
  ],
})

override

Array containing override parameters to override options based on tags/operations/methods/paths.

type

typescript
export type Override = {
  type: 'tag' | 'operationId' | 'path' | 'method'
  pattern: string | RegExp
  options: PluginOptions
}

INFO

Type: Array<Override>

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery(
      {
        override: [
          {
            type: 'tag',
            pattern: 'pet',
            options: {
              output: {
                path: './custom',
              },
            },
          },
        ],
      },
    ),
  ],
})

transformers

transformers.name

Override the name of the hook that is getting generated, this will also override the name of the file.

INFO

Type: (name: string, type?: "function" | "type" | "file" ) => string

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery(
      {
        transformers: {
          name: (name) => {
            return `${name}Hook`
          },
        },
      },
    ),
  ],
})

templates

Make it possible to override one of the templates.

TIP

See templates for more information about creating templates.
Set false to disable a template.

type

typescript
import type { Mutation, Query, QueryOptions, QueryKey } from '@kubb/swagger-tanstack-query/components'

export type Templates = {
  mutation: typeof Mutation.templates | false
  query: typeof Query.templates | false
  queryOptions: typeof QueryOptions.templates | false
  queryKey: typeof QueryKey.templates | false
}

INFO

Type: Templates

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query'
import createSwaggerTS from '@kubb/swagger-ts'

import { templates } from './CustomTemplate'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerTanstackQuery(
      {
        templates,
      },
    ),
  ],
})

Depended

Released under the MIT License.