React Query

The React Query plugin generates TanStack Query helpers for React from your OpenAPI spec. By default you get queryOptions and mutationOptions factories with their query and mutation keys. Set hooks: true to also get useQuery and useMutation hooks.

The plugin ships no HTTP client. Each helper calls a function generated by a client plugin.

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

Or run kubb add plugin-react-query to install the version the Kubb registry pins and add pluginReactQuery() to kubb.config.ts.

Setup

• Add @kubb/plugin-ts and a client plugin: @kubb/plugin-fetch or @kubb/plugin-axios. Leave sdk unset on the client plugin.
• Install @tanstack/react-query 5.82 or a later v5 release in the app that uses the generated code.
• Configure validation on the client plugin, not here.

Options worth knowing

• client picks fetch or axios when both client plugins are registered. A single client is detected automatically.
• hooks adds the use* hooks on top of the option factories.
• suspense: {} adds useSuspenseQuery hooks. It needs hooks: true.
• infinite adds useInfiniteQuery hooks for pagination. It needs hooks: true and covers the operations that take the query parameter named in infinite.queryParam, which defaults to 'id'.
• query and mutation set which HTTP methods become queries (GET) and mutations (POST, PUT, PATCH, DELETE). They also set where the TanStack Query runtime is imported from. Set either to false to skip those helpers.
• customOptions: { importPath } routes every hook through your own function that returns extra options. It needs hooks: true. Kubb creates a starter file at importPath, resolved from the generated hooks folder, when none exists and the path stays inside the plugin's output folder.

See Options for every option and its default.

Example

The config below generates useQuery and useMutation hooks that call the Fetch client.

import { defineConfig } from 'kubb/config'
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({ hooks: true }),
  ],
})