When you go API-First, your OpenAPI contract should be the single source of truth across your entire stack.

Unfortunately, most community-managed generators TanStack Query generators force you into an uncomfortable tradeoff: either live with rigid, inflexible hooks, or write everything by hand and lose the benefits of type safety.

This article shows a more flexible approach.

Use @apical-ts/craft to handle all the heavy, error-prone OpenAPI work: parsing, schema generation, response unions, parameter serialization, and type inference. Then keep a thin, custom generator in your own repository for the TanStack Query layer.

The result: fully typed, clean, and highly ergonomic hooks that you fully own and can evolve as your application needs — without upstream dependencies or duplicated contract logic.

When working with TanStack Query and you want to generate hooks from an OpenAPI contract, you have a few options:

• implement hooks by hand trying to match the contract types
• use a community-managed open source generator for the hooks layer
• or keep a small custom generator in your own repository

This article shows the last option, using @apical-ts/craft to generate the contract-sensitive pieces and a lightweight local generator to emit TanStack Query hooks, as in examples/tanstack-query-hooks/.

The Real Tradeoff Is Ownership

Both the second and third approaches are still code generation. Both start from OpenAPI. What changes is who owns the last mile of the frontend integration.

That difference matters because TanStack Query is intentionally flexible. Query keys, invalidation, mutation side effects, pagination, SSR conventions, and wrapper APIs often end up being application-specific.

The Sweet Spot: Delegate the Hard Part, Own the Hook Layer

With @apical-ts/craft you can generate:

• shared Zod schemas in generated/schemas/*
• route metadata in generated/routes/*
• typed operation functions in generated/client/*

That means your custom hook generator does not need to solve the hardest OpenAPI problems itself. @apical-ts/craft already handles the complex, correctness-sensitive work.

At that point, the TanStack Query layer becomes a much thinner problem: read the generated client and route metadata, then wrap them in useQuery and useMutation the way your application wants.

This is also exactly the kind of layer that can be implemented or evolved very quickly with an AI coding agent.

How It Works

1. Generate the typed client, route metadata, and schemas

npx @apical-ts/craft generate \
  --client \
  -i ./swagger.json \
  -o ./generated

In the example package, this is exposed as:

pnpm run generate:client

2. Run a local generator for the TanStack Query layer

The local generator in scripts/generate-hooks.ts reads the generated client and routes, then emits hook modules under generated/tanstack-query-hooks/*.

Run it in the example template:

pnpm run generate:hooks

or by yourself:

tsx ./scripts/generate-hooks.ts

Example Usage

const { data, error, isLoading } = useFindPetsByStatus({
  query: { status: ["available"] },
});

const addPet = useAddPetMutation();

await addPet.mutateAsync({
  body: { name: "Rex", photoUrls: [] },
});

The generated hooks stay simple and fully typed:

export function useFindPetsByStatus(
  args: Parameters<typeof ops.findPetsByStatus>[0],
) {
  type Result = Awaited<ReturnType<typeof ops.findPetsByStatus>>;

  return useQuery<Result, unknown>({
    queryKey: ["findPetsByStatus", args],
    queryFn: () => ops.findPetsByStatus(args),
  });
}

Why Owning the Hook Layer Matters

Most feature requests for community generators are not about OpenAPI parsing: they’re about customization. Custom query key factories, selective invalidation, pagination helpers, optimistic updates, SSR patterns, etc.

These are exactly the kinds of changes you can implement quickly when you own the layer instead of opening an issue upstream and hoping the customization gets accepted.

Final Take

@apical-ts/craft lets you delegate the hard OpenAPI work while keeping full control over your TanStack Query experience. It’s the best of both worlds: strong types and maximum flexibility.

Ready-to-use example:

You may want to try it yourself:

https://github.com/gunzip/apical-ts/tree/main/examples/tanstack-query-hooks