Generate TanStack Query API helpers

Author: linuxlewis

README.md

@@ -25,7 +25,7 @@ Use `pnpm logs -- --service api --lines 120` to inspect API logs. Use `pnpm seed
 
 See [docs/architecture.md](./docs/architecture.md) for the full picture.
 
-Each business domain follows a strict layered model. The React UI uses TanStack Query for server-state fetching, mutation, caching, and invalidation. HTTP route contracts generate the OpenAPI spec and typed frontend client; see [docs/openapi.md](./docs/openapi.md).
+Each business domain follows a strict layered model. The React UI uses TanStack Query for server-state fetching, mutation, caching, and invalidation. HTTP route contracts generate the OpenAPI spec, typed frontend client, and TanStack Query helper factories; see [docs/openapi.md](./docs/openapi.md).
 
 ```
 Types → Config → Repo → Service → Runtime → UI

docs/architecture.md

@@ -10,7 +10,8 @@ Types → Config → Repo → Service → Runtime → UI
    └── Zod request/response schemas ─────┘       │
                          │                       │
                          ▼                       │
-              OpenAPI spec + typed API client ───┘
+              OpenAPI spec + typed API client
+              + TanStack Query helpers ───────────┘
 ```
 
 ### Layer Responsibilities
@@ -22,9 +23,9 @@ Types → Config → Repo → Service → Runtime → UI
 | **repo/** | Data access, database queries, external API clients | types, config |
 | **service/** | Business logic, orchestration, domain rules | types, config, repo |
 | **runtime/** | Server routes, route contracts, background jobs, event handlers | types, config, repo, service |
-| **ui/** | React components, hooks, pages; uses generated API client for HTTP | types, config (client-safe only), generated client |
+| **ui/** | React components, hooks, pages; uses generated API client and TanStack Query helpers for HTTP | types, config (client-safe only), generated client |
 
-Route contracts live in `runtime/contract.ts` because they describe the HTTP boundary. They depend on lower-layer Zod schemas and provider contract types, then feed generated artifacts under `src/generated/`. UI code may import the generated client and exported client-safe types, but it must not import runtime route modules directly.
+Route contracts live in `runtime/contract.ts` because they describe the HTTP boundary. They depend on lower-layer Zod schemas and provider contract types, then feed generated artifacts under `src/generated/`. UI code may import the generated client, generated TanStack Query option factories, generated query keys, and exported client-safe types, but it must not import runtime route modules directly.
 
 ### Cross-Cutting Concerns (Providers)
 
@@ -47,7 +48,7 @@ These rules are enforced by the custom linter at `lints/check-deps.ts`:
 2. **No cross-domain imports at lower layers.** `domainA/repo` cannot import `domainB/repo`. Cross-domain communication happens at the `service` layer or above.
 3. **No direct cross-cutting imports.** Use `src/providers/`, not raw `pino` or `@opentelemetry/*` imports in domain code.
 4. **UI only imports types and client-safe config.** No server-side code in the UI layer.
-5. **Generated API client is the UI HTTP boundary.** Browser code should call `src/generated/api-client.generated.ts`, not hand-written `fetch` wrappers for app routes.
+5. **Generated API client is the UI HTTP boundary.** Browser code should use `src/generated/api-client.generated.ts`, preferably through generated TanStack Query helpers, not hand-written `fetch` wrappers for app routes.
 6. **Co-located tests are required.** Source modules must have adjacent unit or integration tests unless they are approved entrypoints, generated files, or barrel files.
 7. **Structured logging only.** Application code must not use `console.*`; use providers so stack logs stay queryable.
 

docs/implementation.md

@@ -40,7 +40,7 @@ When a feature adds or changes HTTP behavior:
 2. Add or update the domain route contract in `runtime/contract.ts`, including `method`, `operationId`, `path`, `responses`, and `client` metadata for browser-callable routes.
 3. Register the contract from `src/api-contracts.ts`.
 4. Run `pnpm api:generate` to refresh `src/generated/openapi.generated.json` and `src/generated/api-client.generated.ts`.
-5. Use the generated client from UI code instead of hand-written `fetch` calls.
+5. Use the generated TanStack Query helpers from UI code instead of hand-written `fetch`, `queryKey`, `queryFn`, or `mutationFn` wrappers.
 
 Use [openapi.md](./openapi.md) for the exact contract shape, client metadata fields, and verification checklist.
 

docs/openapi.md

@@ -2,7 +2,7 @@
 
 Last verified: 2026-05-05
 
-The HTTP contract is generated from TypeScript route contract metadata and Zod schemas. Domain runtime layers own their route contracts because routes are the HTTP boundary, and the generated frontend client imports only client-safe domain types.
+The HTTP contract is generated from TypeScript route contract metadata and Zod schemas. Domain runtime layers own their route contracts because routes are the HTTP boundary, and the generated frontend client imports only client-safe domain types. The generated client also exposes TanStack Query option factories so UI code can share query keys, query functions, mutation keys, and mutation functions without hand-written wrappers.
 
 ## Files
 
@@ -12,7 +12,7 @@ The HTTP contract is generated from TypeScript route contract metadata and Zod s
 | App route contract registry | `src/api-contracts.ts` |
 | Example domain route contracts | `src/domains/example/runtime/contract.ts` |
 | Generated OpenAPI spec | `src/generated/openapi.generated.json` |
-| Generated frontend client | `src/generated/api-client.generated.ts` |
+| Generated frontend client and TanStack Query helpers | `src/generated/api-client.generated.ts` |
 
 ## Commands
 
@@ -29,7 +29,7 @@ The HTTP contract is generated from TypeScript route contract metadata and Zod s
 2. Add or update the route contract in the domain `runtime/contract.ts`.
 3. Implement the Fastify route in the domain `runtime/routes.ts`.
 4. Run `pnpm api:generate`.
-5. Use `src/generated/api-client.generated.ts` from UI code instead of hand-written `fetch` calls.
+5. Use `apiQueries`, `apiMutations`, and `apiQueryKeys` from `src/generated/api-client.generated.ts` in UI code instead of hand-written `fetch`, `queryKey`, `queryFn`, or `mutationFn` wrappers.
 
 ## Contract Shape
 
@@ -131,6 +131,56 @@ client: {
 
 For a `DELETE` route that returns `204`, omit `responseParser` and use `responseType: "void"`.
 
+## Generated TanStack Query Helpers
+
+The generator emits three TanStack-oriented surfaces:
+
+| Export | Purpose |
+|--------|---------|
+| `apiQueryKeys` | Stable query key factories for GET routes. Use these for invalidation and cache reads. |
+| `apiQueries` | `queryOptions(...)` factories for GET routes. Pass these directly to `useQuery`, `useSuspenseQuery`, `prefetchQuery`, or `useQueries`. |
+| `apiMutations` | `mutationOptions(...)` factories for non-GET routes. Pass or spread these into `useMutation`. |
+
+Use these helpers in UI code:
+
+```tsx
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+	apiMutations,
+	apiQueries,
+	apiQueryKeys,
+} from "../../../generated/api-client.generated.js";
+
+const itemsQuery = useQuery(apiQueries.listItems());
+
+const createMutation = useMutation({
+	...apiMutations.createItem(),
+	onSuccess: async () => {
+		await queryClient.invalidateQueries({ queryKey: apiQueryKeys.listItems() });
+	},
+});
+```
+
+GET routes generate `apiQueries.<functionName>()`. If the route has path params, the params become the first argument:
+
+```ts
+useQuery(apiQueries.getItem({ id }));
+```
+
+Non-GET routes generate `apiMutations.<functionName>()`. Mutation variables match the generated client method shape:
+
+- body-only routes use the body value as mutation variables
+- path-param-only routes use the params object as mutation variables
+- routes with both path params and body use `{ params, body }`
+- bodyless and paramless routes use no mutation variables
+
+```ts
+createMutation.mutate({ name: "New item", status: "draft" });
+deleteMutation.mutate({ id });
+```
+
+The generated helpers call the generated `apiClient`, so response parsing and `ApiClientError` behavior stay centralized.
+
 ## Schema Rules
 
 - Request schemas should describe the raw JSON sent by clients.
@@ -172,4 +222,4 @@ When changing contracts, verify all of the following:
 2. `runtime/routes.ts` has tests or integration coverage for boundary validation and status codes.
 3. `pnpm api:generate` updates both generated files.
 4. `pnpm api:check` passes without rewriting artifacts.
-5. UI code imports `apiClient` or generated exported types from `src/generated/api-client.generated.ts`.
+5. UI code imports `apiQueries`, `apiMutations`, `apiQueryKeys`, `apiClient`, or generated exported types from `src/generated/api-client.generated.ts`.

scripts/generate-openapi.ts

@@ -46,11 +46,14 @@ function generateClient(routes: readonly ApiRouteContract[]) {
 	const clientRoutes = routes.filter((route) => route.client);
 	const imports = mergeImports(clientRoutes.map((route) => route.client).filter(isDefined));
 	const methods = clientRoutes.map(generateClientMethod).join(",\n\n");
+	const queryRoutes = clientRoutes.filter((route) => route.method === "get");
+	const mutationRoutes = clientRoutes.filter((route) => route.method !== "get");
 
 	return `${[
 		"/* eslint-disable */",
 		"/* This file is generated by scripts/generate-openapi.ts. Do not edit by hand. */",
 		"",
+		'import { mutationOptions, queryOptions } from "@tanstack/react-query";',
 		imports,
 		"",
 		"export interface ApiClientOptions {",
@@ -86,6 +89,12 @@ function generateClient(routes: readonly ApiRouteContract[]) {
 		"",
 		"export const apiClient = createApiClient();",
 		"",
+		generateQueryKeyFactories(queryRoutes),
+		"",
+		generateQueryOptionFactories(queryRoutes),
+		"",
+		generateMutationOptionFactories(mutationRoutes),
+		"",
 		"async function request<TResponse>(",
 		"\tfetchImpl: typeof fetch,",
 		"\tbaseUrl: string,",
@@ -119,9 +128,59 @@ function generateClient(routes: readonly ApiRouteContract[]) {
 	].join("\n")}\n`;
 }
 
+function generateQueryKeyFactories(routes: readonly ApiRouteContract[]) {
+	if (routes.length === 0) return "export const apiQueryKeys = {} as const;";
+
+	const entries = routes.map((route) => {
+		const client = requiredClient(route);
+		const params = client.pathParamsType ? `params: ${client.pathParamsType}` : "";
+		const keyParts = client.pathParamsType
+			? `["api", ${JSON.stringify(client.functionName)}, params] as const`
+			: `["api", ${JSON.stringify(client.functionName)}] as const`;
+		return `${client.functionName}: (${params}) => ${keyParts},`;
+	});
+
+	return `export const apiQueryKeys = {\n${indent(entries.join("\n"), 1)}\n} as const;`;
+}
+
+function generateQueryOptionFactories(routes: readonly ApiRouteContract[]) {
+	if (routes.length === 0) {
+		return "export function createApiQueryOptions(_client = apiClient) {\n\treturn {};\n}\n\nexport const apiQueries = createApiQueryOptions();";
+	}
+
+	const entries = routes.map((route) => {
+		const client = requiredClient(route);
+		const params = client.pathParamsType
+			? `params: ${client.pathParamsType}, options: ApiRequestOptions = {}`
+			: "options: ApiRequestOptions = {}";
+		const keyCall = client.pathParamsType
+			? `apiQueryKeys.${client.functionName}(params)`
+			: `apiQueryKeys.${client.functionName}()`;
+		const clientCall = client.pathParamsType
+			? `client.${client.functionName}(params, options)`
+			: `client.${client.functionName}(options)`;
+		return `${client.functionName}: (${params}) => queryOptions({\n\tqueryKey: ${keyCall},\n\tqueryFn: () => ${clientCall},\n}),`;
+	});
+
+	return `export function createApiQueryOptions(client = apiClient) {\n\treturn {\n${indent(entries.join("\n\n"), 2)}\n\t};\n}\n\nexport const apiQueries = createApiQueryOptions();`;
+}
+
+function generateMutationOptionFactories(routes: readonly ApiRouteContract[]) {
+	if (routes.length === 0) {
+		return "export function createApiMutationOptions(_client = apiClient) {\n\treturn {};\n}\n\nexport const apiMutations = createApiMutationOptions();";
+	}
+
+	const entries = routes.map((route) => {
+		const client = requiredClient(route);
+		const mutationFn = mutationFunction(client);
+		return `${client.functionName}: (options: ApiRequestOptions = {}) => mutationOptions({\n\tmutationKey: ["api", ${JSON.stringify(client.functionName)}] as const,\n\tmutationFn: ${mutationFn},\n}),`;
+	});
+
+	return `export function createApiMutationOptions(client = apiClient) {\n\treturn {\n${indent(entries.join("\n\n"), 2)}\n\t};\n}\n\nexport const apiMutations = createApiMutationOptions();`;
+}
+
 function generateClientMethod(route: ApiRouteContract) {
-	const client = route.client;
-	if (!client) throw new Error(`Route ${route.operationId} is missing client metadata.`);
+	const client = requiredClient(route);
 
 	const params = methodParameters(client);
 	const path = client.pathParamsType ? pathTemplate(route.path) : JSON.stringify(route.path);
@@ -132,6 +191,27 @@ function generateClientMethod(route: ApiRouteContract) {
 	return `${client.functionName}(${params}): Promise<${client.responseType}> {\n\treturn request<${client.responseType}>(fetchImpl, baseUrl, ${JSON.stringify(route.method.toUpperCase())}, ${path}, options${bodyArg}${parseArg});\n}`;
 }
 
+function requiredClient(route: ApiRouteContract) {
+	if (!route.client) throw new Error(`Route ${route.operationId} is missing client metadata.`);
+	return route.client;
+}
+
+function mutationFunction(client: ApiClientContract) {
+	if (client.pathParamsType && client.requestBodyType) {
+		return `(variables: { params: ${client.pathParamsType}; body: ${client.requestBodyType} }) => client.${client.functionName}(variables.params, variables.body, options)`;
+	}
+
+	if (client.pathParamsType) {
+		return `(params: ${client.pathParamsType}) => client.${client.functionName}(params, options)`;
+	}
+
+	if (client.requestBodyType) {
+		return `(body: ${client.requestBodyType}) => client.${client.functionName}(body, options)`;
+	}
+
+	return `() => client.${client.functionName}(options)`;
+}
+
 function methodParameters(client: ApiClientContract) {
 	const params: string[] = [];
 	if (client.pathParamsType) params.push(`params: ${client.pathParamsType}`);

src/domains/example/ui/item-list.tsx

@@ -12,41 +12,37 @@ import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useState } from "react";
 import {
 	ApiClientError,
-	apiClient,
-	type ItemResponse,
+	apiMutations,
+	apiQueries,
+	apiQueryKeys,
 } from "../../../generated/api-client.generated.js";
 
-const itemsQueryKey = ["items"] as const;
-
 export function ItemList() {
 	const [newName, setNewName] = useState("");
 	const queryClient = useQueryClient();
 
-	const itemsQuery = useQuery({
-		queryKey: itemsQueryKey,
-		queryFn: fetchItems,
-	});
+	const itemsQuery = useQuery(apiQueries.listItems());
 
 	const createMutation = useMutation({
-		mutationFn: createItemRequest,
+		...apiMutations.createItem(),
 		onSuccess: async () => {
 			setNewName("");
-			await queryClient.invalidateQueries({ queryKey: itemsQueryKey });
+			await queryClient.invalidateQueries({ queryKey: apiQueryKeys.listItems() });
 		},
 	});
 
 	const deleteMutation = useMutation({
-		mutationFn: deleteItemRequest,
+		...apiMutations.deleteItem(),
 		onSuccess: async () => {
-			await queryClient.invalidateQueries({ queryKey: itemsQueryKey });
+			await queryClient.invalidateQueries({ queryKey: apiQueryKeys.listItems() });
 		},
 	});
 
 	const error = getErrorMessage(itemsQuery.error ?? createMutation.error ?? deleteMutation.error);
 
 	function createItem() {
 		if (!newName.trim()) return;
-		createMutation.mutate(newName);
+		createMutation.mutate({ name: newName, status: "draft" });
 	}
 
 	if (itemsQuery.isLoading) return <p>Loading...</p>;
@@ -93,7 +89,7 @@ export function ItemList() {
 							</span>
 							<button
 								type="button"
-								onClick={() => deleteMutation.mutate(item.id)}
+								onClick={() => deleteMutation.mutate({ id: item.id })}
 								style={{ color: "red", cursor: "pointer" }}
 							>
 								Delete
@@ -106,18 +102,6 @@ export function ItemList() {
 	);
 }
 
-async function fetchItems(): Promise<ItemResponse[]> {
-	return apiClient.listItems();
-}
-
-async function createItemRequest(name: string) {
-	return apiClient.createItem({ name, status: "draft" });
-}
-
-async function deleteItemRequest(id: string) {
-	await apiClient.deleteItem({ id });
-}
-
 function getErrorMessage(error: unknown) {
 	if (!error) return null;
 	if (error instanceof ApiClientError) return `HTTP ${error.status}`;

src/generated/api-client.generated.ts

@@ -1,6 +1,7 @@
 /* eslint-disable */
 /* This file is generated by scripts/generate-openapi.ts. Do not edit by hand. */
 
+import { mutationOptions, queryOptions } from "@tanstack/react-query";
 import type { CreateItem, ItemResponse } from "../domains/example/types/index.js";
 export type { CreateItem, ItemResponse } from "../domains/example/types/index.js";
 import { ItemResponseSchema } from "../domains/example/types/index.js";
@@ -52,6 +53,43 @@ export function createApiClient(options: ApiClientOptions = {}) {
 
 export const apiClient = createApiClient();
 
+export const apiQueryKeys = {
+	listItems: () => ["api", "listItems"] as const,
+	getItem: (params: { id: string }) => ["api", "getItem", params] as const,
+} as const;
+
+export function createApiQueryOptions(client = apiClient) {
+	return {
+		listItems: (options: ApiRequestOptions = {}) => queryOptions({
+			queryKey: apiQueryKeys.listItems(),
+			queryFn: () => client.listItems(options),
+		}),
+
+		getItem: (params: { id: string }, options: ApiRequestOptions = {}) => queryOptions({
+			queryKey: apiQueryKeys.getItem(params),
+			queryFn: () => client.getItem(params, options),
+		}),
+	};
+}
+
+export const apiQueries = createApiQueryOptions();
+
+export function createApiMutationOptions(client = apiClient) {
+	return {
+		createItem: (options: ApiRequestOptions = {}) => mutationOptions({
+			mutationKey: ["api", "createItem"] as const,
+			mutationFn: (body: CreateItem) => client.createItem(body, options),
+		}),
+
+		deleteItem: (options: ApiRequestOptions = {}) => mutationOptions({
+			mutationKey: ["api", "deleteItem"] as const,
+			mutationFn: (params: { id: string }) => client.deleteItem(params, options),
+		}),
+	};
+}
+
+export const apiMutations = createApiMutationOptions();
+
 async function request<TResponse>(
 	fetchImpl: typeof fetch,
 	baseUrl: string,