@kubb/plugin-react-query

@kubb/plugin-react-query turns each OpenAPI operation into a TanStack Query hook for React. Read operations become useFoo, with useFooSuspense and useFooInfinite variants. Write operations become useFoo mutations. Every hook is typed: query keys, input variables, response data, and error shape all come from the spec.

The hooks call an HTTP client, so a client plugin must be registered: @kubb/plugin-ts for the types, plus either @kubb/plugin-axios or @kubb/plugin-fetch for the client.

Each hook takes its parameters as a single grouped options object shaped as { body, path, query, headers }, with camelCase property names. The request still sends the original parameter names from the spec, and Kubb writes that mapping for you.

Installation ​

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

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

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

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

Dependencies ​

This plugin needs these plugins in your config:

• @kubb/plugin-ts for the types.
• A client plugin, @kubb/plugin-axios or @kubb/plugin-fetch, for the HTTP layer. The hooks call its functions, so generation errors out when no client plugin is registered.

For runtime validation, set validator on the client plugin. The generated operations carry the validation, so the hooks get it for free.

Example ​

import { defineConfig } from 'kubb'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginFetch } from '@kubb/plugin-fetch'
import { pluginReactQuery } from '@kubb/plugin-react-query'

export default defineConfig({
  input: './petStore.yaml',
  output: { path: './src/gen' },
  plugins: [
    pluginTs(),
    pluginFetch(),
    pluginReactQuery({
      output: { path: './hooks', mode: 'directory' },
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Hooks`,
      },
      client: 'fetch',
      mutation: { methods: ['POST', 'PUT', 'DELETE'] },
      infinite: {
        queryParam: 'next_page',
        initialPageParam: 0,
        nextParam: 'pagination.next.cursor',
        previousParam: ['pagination', 'prev', 'cursor'],
      },
      query: {
        methods: ['GET'],
        importPath: '@tanstack/react-query',
      },
      suspense: {},
    }),
  ],
})

See also ​

• TanStack Query
• Changelog