Skip to content
These docs describe v4, which is in beta: install it with @beta. For v3, read the docs in the v3 branch.

FAQ

What does OpenAPI React Query Codegen generate?

Section titled “What does OpenAPI React Query Codegen generate?”

It reads an OpenAPI document and writes two directories. openapi/requests/ is a typed HTTP client: one function per operation, the request and response types, and a small fetch or axios runtime. openapi/queries/ is TanStack Query (React Query) v5 code on top of it: for every GET operation a useQuery hook, a suspense hook, a queryOptions factory, a prefetch function, an ensureQueryData function and a query key function, and for every other operation a useMutation hook. See Introduction.

@7nohe/openapi-react-query-codegen. Its command is orqc (openapi-rq also works). The same package is published as @7nohe/orqc so that npx @7nohe/orqc@beta -i ./openapi.yaml is short to type. The unscoped openapi-react-query-codegen and openapi-rq packages on npm, and copies under other scopes, are not published by this project.

v4 is in beta. npm install -D @7nohe/openapi-react-query-codegen@beta installs it; without @beta npm installs v3. This site describes v4. The v3 documentation is in the v3 branch of the repository, and Migrating to v4 lists what changes.

Node.js 24 or later to run the generator, and @tanstack/react-query 5 in the project. The generated code compiles with TypeScript 5, 6 and 7 and has no Node.js requirement of its own.

Does it work with Vue, Svelte, Solid or Angular?

Section titled “Does it work with Vue, Svelte, Solid or Angular?”

No. The generated hooks are for React. For another framework, see Comparison.

OpenAPI 3.0 and 3.1, in YAML or JSON, including external $refs to files and URLs. Swagger/OpenAPI 2.0 documents are rejected with an error: convert them to OpenAPI 3 first.

Yes. -i takes a file path or an http(s) URL.

What if my operations have no operationId?

Section titled “What if my operations have no operationId?”

They are named after the method and the path, such as getPetsById. --noOperationId names every operation that way.

That is the project's choice. If you commit it, run the generator with --check in CI, so that a change to the specification cannot be merged without regenerating.

No. The next run overwrites them. Change the specification or the flags and regenerate. To change how one request is made, configure the client or pass options to the hook.

Does the generated code need a runtime package?

Section titled “Does the generated code need a runtime package?”

Only @tanstack/react-query, and axios if you generate with -c axios. The fetch runtime is written into openapi/requests/runtime.gen.ts, and nothing in the output imports this package.

fetch is the default and needs no package. Choose -c axios when the project already configures axios (instances, interceptors, adapters) and you want the generated client to use it.

How do I set the base URL and send a token?

Section titled “How do I set the base URL and send a token?”

Configure the generated client once, before the first request:

import { client } from "./openapi/requests/client.gen";
client.setConfig({
baseUrl: "https://api.example.com",
// Sent with every operation that declares `security` in the specification.
auth: () => localStorage.getItem("token") ?? undefined,
});

For a header on every request, whatever the specification says, add a request interceptor:

client.interceptors.request.use((request) => {
request.headers.set("X-Tenant", "acme");
return request;
});

With the axios client the option is baseURL, and interceptors are registered on the axios instance: client.instance.interceptors.request.use(...). See Configuring the Client for cookies, response and error interceptors, and options for one request.

The generated hooks reject on an error response, so error and isError are set on queries and onError runs on mutations, with the error typed from the responses the specification declares.

A GET operation gets useXxxInfinite when it has a query parameter with the name given by --pageParam (default page). --nextPageParam (default nextPage, dot notation for nested values) is the response property the generated getNextPageParam reads; when your API signals the next page differently, pass your own getNextPageParam to the hook. See Usage.

Does it work with Next.js App Router and other SSR frameworks?

Section titled “Does it work with Next.js App Router and other SSR frameworks?”

Yes. Prefetch on the server with the generated prefetchUseXxx or ensureUseXxxData functions and hydrate on the client. There are examples for Next.js, React Router and TanStack Router.

No. It writes the schemas of the specification as JSON Schema constants to openapi/requests/schemas.gen.ts (turn that off with --noSchemas), which form and validation libraries that accept JSON Schema can use.

Yes. --mock msw writes mock data and MSW request handlers for every operation. The values are fixed and taken from the specification. See Mocking with MSW.

How do I keep the generated code up to date in CI?

Section titled “How do I keep the generated code up to date in CI?”

Run the same command with --check. It generates into a temporary directory, changes nothing, and exits with 1 when the committed output differs. --json prints errors as one line of JSON. See CI and Coding Agents.

Add --agentsMd to the command. It keeps a short block in the project's AGENTS.md (or the file you name) that tells the agent how to find one operation with grep instead of reading the generated files. The package also ships its own AGENTS.md, and this site serves llms.txt. See CI and Coding Agents.

How does it relate to @hey-api/openapi-ts?

Section titled “How does it relate to @hey-api/openapi-ts?”

Up to v3 the client in openapi/requests/ was produced by @hey-api/openapi-ts and this package generated the hooks on top. Since v4 the client generator is part of this package, and @hey-api/openapi-ts is no longer a dependency. The hooks keep their names and signatures. See Migrating to v4.

How does it compare with Orval, Kubb, Hey API and openapi-react-query?

Section titled “How does it compare with Orval, Kubb, Hey API and openapi-react-query?”

See Comparison for what each generates, and Benchmarks for generation time, install size and type errors in the output.