feat: add TanStack Router integration with loader factories

Author: 7nohe

README.md

@@ -10,3 +10,73 @@
 - Generates custom functions that use React Query's `ensureQueryData` and `prefetchQuery` functions
 - Generates query keys and functions for query caching
 - Generates pure TypeScript clients generated by [@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts)
+- Generates loader factories and helpers for [TanStack Router](https://tanstack.com/router) integration
+
+## TanStack Router Integration
+
+The generated `router.ts` file provides loader factories and helpers for seamless integration with TanStack Router.
+
+### Using Loader Factories
+
+Use `loaderUse*` functions in your route definitions to prefetch data:
+
+```tsx
+// routes/pets.$petId.tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { loaderUseFindPetById } from "../openapi/queries/router";
+import { queryClient } from "../queryClient";
+
+export const Route = createFileRoute("/pets/$petId")({
+  loader: ({ params }) =>
+    loaderUseFindPetById({ queryClient })({
+      params: { petId: Number(params.petId) },
+    }),
+  component: PetDetail,
+});
+```
+
+For SSR/TanStack Start, pass `queryClient` from the router context:
+
+```tsx
+loader: ({ context, params }) =>
+  loaderUseFindPetById({ queryClient: context.queryClient })({
+    params: { petId: Number(params.petId) },
+  }),
+```
+
+### Using withQueryPrefetch for Hover/Touch Prefetching
+
+The `withQueryPrefetch` helper enables prefetching on hover or touch:
+
+```tsx
+import { withQueryPrefetch } from "../openapi/queries/router";
+import { prefetchUseFindPetById } from "../openapi/queries/prefetch";
+import { queryClient } from "../queryClient";
+
+function PetLink({ petId }: { petId: number }) {
+  return (
+    <a
+      href={`/pets/${petId}`}
+      {...withQueryPrefetch(() =>
+        prefetchUseFindPetById(queryClient, { path: { petId } })
+      )}
+    >
+      View Pet
+    </a>
+  );
+}
+```
+
+### Important Notes
+
+- **Router params are strings**: TanStack Router params are always strings. You must parse them to the correct type (e.g., `Number(params.petId)`) before passing to the loader.
+- **External cache configuration**: When using TanStack Query as the cache, set `defaultPreloadStaleTime: 0` in your router configuration to let React Query handle cache freshness:
+
+```tsx
+const router = createRouter({
+  routeTree,
+  defaultPreloadStaleTime: 0,
+});
+```
+
+- **Link preloading**: When using `<Link preload="intent">` or `defaultPreload: "intent"`, TanStack Router will automatically call the route's `loader` on hover/touch. If your loader uses `ensureUse*Data`, prefetching happens automatically without needing `withQueryPrefetch`.

docs/src/content/docs/examples/tanstack-router.md

@@ -1,6 +1,174 @@
 ---
 title: TanStack Router Example
-description: A simple example of using TanStack Router with OpenAPI React Query Codegen.
+description: Using TanStack Router with OpenAPI React Query Codegen for data loading and prefetching.
 ---
 
-Example of using Next.js can be found in the [`examples/tanstack-router-app`](https://github.com/7nohe/openapi-react-query-codegen/tree/main/examples/tanstack-router-app) directory of the repository.
+Example of using TanStack Router can be found in the [`examples/tanstack-router-app`](https://github.com/7nohe/openapi-react-query-codegen/tree/main/examples/tanstack-router-app) directory of the repository.
+
+## Generated Files
+
+The codegen generates a `router.ts` file that provides:
+
+- **Loader factories** (`loaderUse*`) for route data loading
+- **`withQueryPrefetch`** helper for hover/touch prefetching
+
+## Using Loader Factories
+
+Use `loaderUse*` functions in your route definitions to prefetch data before the route renders:
+
+```tsx
+// routes/pets.$petId.tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { loaderUseFindPetById } from "../openapi/queries/router";
+import { queryClient } from "../queryClient";
+
+export const Route = createFileRoute("/pets/$petId")({
+  loader: ({ params }) =>
+    loaderUseFindPetById({ queryClient })({
+      params: { petId: Number(params.petId) },
+    }),
+  component: PetDetail,
+});
+
+function PetDetail() {
+  const { petId } = Route.useParams();
+  const { data } = useFindPetById({ path: { petId: Number(petId) } });
+
+  return <div>{data?.name}</div>;
+}
+```
+
+### For SSR / TanStack Start
+
+When using SSR or TanStack Start, pass `queryClient` from the router context instead of importing it directly:
+
+```tsx
+export const Route = createFileRoute("/pets/$petId")({
+  loader: ({ context, params }) =>
+    loaderUseFindPetById({ queryClient: context.queryClient })({
+      params: { petId: Number(params.petId) },
+    }),
+  component: PetDetail,
+});
+```
+
+### Operations Without Path Parameters
+
+For operations without path parameters, the loader is simpler:
+
+```tsx
+import { loaderUseFindPets } from "../openapi/queries/router";
+
+export const Route = createFileRoute("/pets")({
+  loader: () => loaderUseFindPets({ queryClient })(),
+  component: PetList,
+});
+```
+
+### Passing Additional Options
+
+You can pass additional client options through the `clientOptions` parameter:
+
+```tsx
+loader: ({ params }) =>
+  loaderUseFindPetById({
+    queryClient,
+    clientOptions: {
+      headers: { "X-Custom-Header": "value" },
+    },
+  })({
+    params: { petId: Number(params.petId) },
+  }),
+```
+
+## Using withQueryPrefetch
+
+The `withQueryPrefetch` helper enables prefetching on hover or touch events. This is useful for custom prefetch triggers outside of TanStack Router's built-in `<Link>` preloading:
+
+```tsx
+import { withQueryPrefetch } from "../openapi/queries/router";
+import { prefetchUseFindPetById } from "../openapi/queries/prefetch";
+import { queryClient } from "../queryClient";
+
+function PetLink({ petId }: { petId: number }) {
+  return (
+    <a
+      href={`/pets/${petId}`}
+      {...withQueryPrefetch(() =>
+        prefetchUseFindPetById(queryClient, { path: { petId } })
+      )}
+    >
+      View Pet
+    </a>
+  );
+}
+```
+
+This spreads `onMouseEnter` and `onTouchStart` handlers that trigger the prefetch.
+
+## Router Configuration
+
+### External Cache Settings
+
+When using TanStack Query as an external cache, configure the router to delegate cache freshness to React Query:
+
+```tsx
+import { createRouter } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen";
+
+const router = createRouter({
+  routeTree,
+  defaultPreloadStaleTime: 0, // Let React Query handle cache freshness
+});
+```
+
+### Link Preloading
+
+TanStack Router's `<Link>` component supports intent-based preloading:
+
+```tsx
+<Link to="/pets/$petId" params={{ petId: "1" }} preload="intent">
+  View Pet
+</Link>
+```
+
+Or set it globally:
+
+```tsx
+const router = createRouter({
+  routeTree,
+  defaultPreload: "intent",
+  defaultPreloadStaleTime: 0,
+});
+```
+
+When using `preload="intent"`, the router automatically calls the route's `loader` on hover/touch. If your loader uses `ensureUse*Data` (which the generated loaders do), prefetching happens automatically.
+
+## Important Notes
+
+### Router Params Are Strings
+
+TanStack Router params are always strings. You must parse them to the correct type before passing to the loader:
+
+```tsx
+// Router params: { petId: string }
+// API expects: { petId: number }
+loader: ({ params }) =>
+  loaderUseFindPetById({ queryClient })({
+    params: { petId: Number(params.petId) }, // Convert string to number
+  }),
+```
+
+For type-safe parsing, consider using TanStack Router's `parseParams`:
+
+```tsx
+export const Route = createFileRoute("/pets/$petId")({
+  parseParams: (params) => ({
+    petId: Number(params.petId),
+  }),
+  loader: ({ params }) =>
+    loaderUseFindPetById({ queryClient })({
+      params: { petId: params.petId }, // Already a number
+    }),
+});
+```

docs/src/content/docs/guides/introduction.mdx

@@ -12,6 +12,7 @@ OpenAPI React Query Codegen is a code generator for creating React Query (also k
 - Generates custom functions that use React Query's `ensureQueryData` and `prefetchQuery` functions
 - Generates query keys and functions for query caching
 - Generates pure TypeScript clients generated by [@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts)
+- Generates loader factories and helpers for [TanStack Router](https://tanstack.com/router) integration
 
 
 ## Installation
@@ -75,6 +76,7 @@ openapi/
 │   ├── infiniteQueries.ts
 │   ├── prefetch.ts
 │   ├── queries.ts
+│   ├── router.ts
 │   └── suspense.ts
 └── requests
     ├── index.ts
@@ -177,8 +179,9 @@ export default App;
     - ensureQueryData.ts Generated ensureQueryData functions
     - queries.ts Generated query/mutation hooks
     - infiniteQueries.ts Generated infinite query hooks
-    - suspenses.ts Generated suspense hooks
+    - suspense.ts Generated suspense hooks
     - prefetch.ts Generated prefetch functions
+    - router.ts Generated loader factories and helpers for TanStack Router
   - requests Output code generated by `@hey-api/openapi-ts`
 
 </FileTree>

docs/src/content/docs/index.mdx

@@ -24,7 +24,7 @@ import { Card, CardGrid } from '@astrojs/starlight/components';
 		Generates custom react hooks that use React(TanStack) Query's useQuery, useSuspenseQuery, useMutation and useInfiniteQuery hooks.
 	</Card>
 	<Card title="Prefetching & Router Integration" icon="vercel">
-		Generates custom functions that use React Query's `ensureQueryData` and `prefetchQuery` functions to integrate into frameworks like Next.js and Remix.
+		Generates custom functions that use React Query's `ensureQueryData` and `prefetchQuery` functions, plus loader factories for TanStack Router, to integrate into frameworks like Next.js, Remix, and TanStack Start.
 	</Card>
 	<Card title="Pure TypeScript Clients" icon="seti:typescript">
 		Generates pure TypeScript clients generated by [@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts) in case you still want to do type-safe API calls without React Query.

src/constants.mts

@@ -13,4 +13,5 @@ export const OpenApiRqFiles = {
   index: "index",
   prefetch: "prefetch",
   ensureQueryData: "ensureQueryData",
+  router: "router",
 } as const;