Skip to content

Commit 8f7bfdd

Browse files
7nohe7nohe
committed
docs: add TanStack Router integration guide using ensureQueryData
1 parent 664744c commit 8f7bfdd

File tree

11 files changed

+27
-599
lines changed

11 files changed

+27
-599
lines changed

‎README.md‎

Lines changed: 0 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -10,73 +10,3 @@
1010
- Generates custom functions that use React Query's `ensureQueryData` and `prefetchQuery` functions
1111
- Generates query keys and functions for query caching
1212
- Generates pure TypeScript clients generated by [@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts)
13-
- Generates loader factories and helpers for [TanStack Router](https://tanstack.com/router) integration
14-
15-
## TanStack Router Integration
16-
17-
The generated `router.ts` file provides loader factories and helpers for seamless integration with TanStack Router.
18-
19-
### Using Loader Factories
20-
21-
Use `loaderUse*` functions in your route definitions to prefetch data:
22-
23-
```tsx
24-
// routes/pets.$petId.tsx
25-
import { createFileRoute } from "@tanstack/react-router";
26-
import { loaderUseFindPetById } from "../openapi/queries/router";
27-
import { queryClient } from "../queryClient";
28-
29-
export const Route = createFileRoute("/pets/$petId")({
30-
loader: ({ params }) =>
31-
loaderUseFindPetById({ queryClient })({
32-
params: { petId: Number(params.petId) },
33-
}),
34-
component: PetDetail,
35-
});
36-
```
37-
38-
For SSR/TanStack Start, pass `queryClient` from the router context:
39-
40-
```tsx
41-
loader: ({ context, params }) =>
42-
loaderUseFindPetById({ queryClient: context.queryClient })({
43-
params: { petId: Number(params.petId) },
44-
}),
45-
```
46-
47-
### Using withQueryPrefetch for Hover/Touch Prefetching
48-
49-
The `withQueryPrefetch` helper enables prefetching on hover or touch:
50-
51-
```tsx
52-
import { withQueryPrefetch } from "../openapi/queries/router";
53-
import { prefetchUseFindPetById } from "../openapi/queries/prefetch";
54-
import { queryClient } from "../queryClient";
55-
56-
function PetLink({ petId }: { petId: number }) {
57-
return (
58-
<a
59-
href={`/pets/${petId}`}
60-
{...withQueryPrefetch(() =>
61-
prefetchUseFindPetById(queryClient, { path: { petId } })
62-
)}
63-
>
64-
View Pet
65-
</a>
66-
);
67-
}
68-
```
69-
70-
### Important Notes
71-
72-
- **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.
73-
- **External cache configuration**: When using TanStack Query as the cache, set `defaultPreloadStaleTime: 0` in your router configuration to let React Query handle cache freshness:
74-
75-
```tsx
76-
const router = createRouter({
77-
routeTree,
78-
defaultPreloadStaleTime: 0,
79-
});
80-
```
81-
82-
- **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‎

Lines changed: 25 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -5,27 +5,21 @@ description: Using TanStack Router with OpenAPI React Query Codegen for data loa
55

66
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.
77

8-
## Generated Files
8+
## Route Data Loading
99

10-
The codegen generates a `router.ts` file that provides:
11-
12-
- **Loader factories** (`loaderUse*`) for route data loading
13-
- **`withQueryPrefetch`** helper for hover/touch prefetching
14-
15-
## Using Loader Factories
16-
17-
Use `loaderUse*` functions in your route definitions to prefetch data before the route renders:
10+
Use the generated `ensureQueryData` functions in your route loaders to prefetch data before the route renders:
1811

1912
```tsx
2013
// routes/pets.$petId.tsx
2114
import { createFileRoute } from "@tanstack/react-router";
22-
import { loaderUseFindPetById } from "../openapi/queries/router";
15+
import { ensureUseFindPetByIdData } from "../openapi/queries/ensureQueryData";
16+
import { useFindPetById } from "../openapi/queries";
2317
import { queryClient } from "../queryClient";
2418

2519
export const Route = createFileRoute("/pets/$petId")({
2620
loader: ({ params }) =>
27-
loaderUseFindPetById({ queryClient })({
28-
params: { petId: Number(params.petId) },
21+
ensureUseFindPetByIdData(queryClient, {
22+
path: { petId: Number(params.petId) },
2923
}),
3024
component: PetDetail,
3125
});
@@ -40,72 +34,54 @@ function PetDetail() {
4034

4135
### For SSR / TanStack Start
4236

43-
When using SSR or TanStack Start, pass `queryClient` from the router context instead of importing it directly:
37+
When using SSR or TanStack Start, pass `queryClient` from the router context:
4438

4539
```tsx
4640
export const Route = createFileRoute("/pets/$petId")({
4741
loader: ({ context, params }) =>
48-
loaderUseFindPetById({ queryClient: context.queryClient })({
49-
params: { petId: Number(params.petId) },
42+
ensureUseFindPetByIdData(context.queryClient, {
43+
path: { petId: Number(params.petId) },
5044
}),
5145
component: PetDetail,
5246
});
5347
```
5448

5549
### Operations Without Path Parameters
5650

57-
For operations without path parameters, the loader is simpler:
58-
5951
```tsx
60-
import { loaderUseFindPets } from "../openapi/queries/router";
52+
import { ensureUseFindPetsData } from "../openapi/queries/ensureQueryData";
6153

6254
export const Route = createFileRoute("/pets")({
63-
loader: () => loaderUseFindPets({ queryClient })(),
55+
loader: () => ensureUseFindPetsData(queryClient),
6456
component: PetList,
6557
});
6658
```
6759

68-
### Passing Additional Options
60+
## Prefetching on Hover/Touch
6961

70-
You can pass additional client options through the `clientOptions` parameter:
62+
Use `prefetchQuery` functions for custom prefetch triggers:
7163

7264
```tsx
73-
loader: ({ params }) =>
74-
loaderUseFindPetById({
75-
queryClient,
76-
clientOptions: {
77-
headers: { "X-Custom-Header": "value" },
78-
},
79-
})({
80-
params: { petId: Number(params.petId) },
81-
}),
82-
```
83-
84-
## Using withQueryPrefetch
85-
86-
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:
87-
88-
```tsx
89-
import { withQueryPrefetch } from "../openapi/queries/router";
9065
import { prefetchUseFindPetById } from "../openapi/queries/prefetch";
9166
import { queryClient } from "../queryClient";
9267

9368
function PetLink({ petId }: { petId: number }) {
69+
const handlePrefetch = () => {
70+
prefetchUseFindPetById(queryClient, { path: { petId } });
71+
};
72+
9473
return (
9574
<a
9675
href={`/pets/${petId}`}
97-
{...withQueryPrefetch(() =>
98-
prefetchUseFindPetById(queryClient, { path: { petId } })
99-
)}
76+
onMouseEnter={handlePrefetch}
77+
onTouchStart={handlePrefetch}
10078
>
10179
View Pet
10280
</a>
10381
);
10482
}
10583
```
10684

107-
This spreads `onMouseEnter` and `onTouchStart` handlers that trigger the prefetch.
108-
10985
## Router Configuration
11086

11187
### External Cache Settings
@@ -142,20 +118,18 @@ const router = createRouter({
142118
});
143119
```
144120

145-
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.
121+
When using `preload="intent"`, the router automatically calls the route's `loader` on hover/touch.
146122

147123
## Important Notes
148124

149125
### Router Params Are Strings
150126

151-
TanStack Router params are always strings. You must parse them to the correct type before passing to the loader:
127+
TanStack Router params are always strings. You must parse them to the correct type:
152128

153129
```tsx
154-
// Router params: { petId: string }
155-
// API expects: { petId: number }
156130
loader: ({ params }) =>
157-
loaderUseFindPetById({ queryClient })({
158-
params: { petId: Number(params.petId) }, // Convert string to number
131+
ensureUseFindPetByIdData(queryClient, {
132+
path: { petId: Number(params.petId) }, // Convert string to number
159133
}),
160134
```
161135

@@ -167,8 +141,8 @@ export const Route = createFileRoute("/pets/$petId")({
167141
petId: Number(params.petId),
168142
}),
169143
loader: ({ params }) =>
170-
loaderUseFindPetById({ queryClient })({
171-
params: { petId: params.petId }, // Already a number
144+
ensureUseFindPetByIdData(queryClient, {
145+
path: { petId: params.petId }, // Already a number
172146
}),
173147
});
174148
```

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

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@ OpenAPI React Query Codegen is a code generator for creating React Query (also k
1212
- Generates custom functions that use React Query's `ensureQueryData` and `prefetchQuery` functions
1313
- Generates query keys and functions for query caching
1414
- Generates pure TypeScript clients generated by [@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts)
15-
- Generates loader factories and helpers for [TanStack Router](https://tanstack.com/router) integration
1615

1716

1817
## Installation
@@ -76,7 +75,6 @@ openapi/
7675
│ ├── infiniteQueries.ts
7776
│ ├── prefetch.ts
7877
│ ├── queries.ts
79-
│ ├── router.ts
8078
│ └── suspense.ts
8179
└── requests
8280
├── index.ts
@@ -181,7 +179,6 @@ export default App;
181179
- infiniteQueries.ts Generated infinite query hooks
182180
- suspense.ts Generated suspense hooks
183181
- prefetch.ts Generated prefetch functions
184-
- router.ts Generated loader factories and helpers for TanStack Router
185182
- requests Output code generated by `@hey-api/openapi-ts`
186183

187184
</FileTree>

‎docs/src/content/docs/index.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ import { Card, CardGrid } from '@astrojs/starlight/components';
2424
Generates custom react hooks that use React(TanStack) Query's useQuery, useSuspenseQuery, useMutation and useInfiniteQuery hooks.
2525
</Card>
2626
<Card title="Prefetching & Router Integration" icon="vercel">
27-
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.
27+
Generates custom functions that use React Query's `ensureQueryData` and `prefetchQuery` functions to integrate into frameworks like Next.js, Remix, and TanStack Router.
2828
</Card>
2929
<Card title="Pure TypeScript Clients" icon="seti:typescript">
3030
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‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,5 +13,4 @@ export const OpenApiRqFiles = {
1313
index: "index",
1414
prefetch: "prefetch",
1515
ensureQueryData: "ensureQueryData",
16-
router: "router",
1716
} as const;

‎src/tsmorph/buildRouter.mts‎

Lines changed: 0 additions & 130 deletions
This file was deleted.

0 commit comments

Comments
 (0)