@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. Add @kubb/plugin-ts for the types and either @kubb/plugin-axios or @kubb/plugin-fetch for the client. Generation errors out when no client plugin is present.

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

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

pnpm

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

npm

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

yarn

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

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

kubb.config.ts

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' },
      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