From 0f0601a37405bfd1bba7619805a39bb352bf2e16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Curley?= Date: Sat, 4 Apr 2026 19:55:19 +0100 Subject: [PATCH] docs for new query methods --- docs/router/eslint/create-route-property-order.md | 8 ++++---- docs/router/guide/deferred-data-loading.md | 8 ++++---- docs/router/guide/external-data-loading.md | 4 ++-- docs/router/guide/router-context.md | 3 ++- docs/router/guide/type-safety.md | 6 +++--- docs/router/how-to/setup-testing.md | 3 ++- docs/router/integrations/query.md | 4 ++-- docs/start/framework/react/comparison.md | 2 +- 8 files changed, 20 insertions(+), 18 deletions(-) diff --git a/docs/router/eslint/create-route-property-order.md b/docs/router/eslint/create-route-property-order.md index c22aa7c52d4..72ec1f9db5a 100644 --- a/docs/router/eslint/create-route-property-order.md +++ b/docs/router/eslint/create-route-property-order.md @@ -37,7 +37,7 @@ import { createFileRoute } from '@tanstack/react-router' export const Route = createFileRoute('/path')({ loader: async ({ context }) => { - await context.queryClient.ensureQueryData(getQueryOptions(context.hello)) + await context.queryClient.query({ ...getQueryOptions(context.hello), staleTime: 'static' }) }, beforeLoad: () => ({ hello: 'world' }), }) @@ -55,7 +55,7 @@ import { createFileRoute } from '@tanstack/solid-router' export const Route = createFileRoute('/path')({ loader: async ({ context }) => { - await context.queryClient.ensureQueryData(getQueryOptions(context.hello)) + await context.queryClient.query({ ...getQueryOptions(context.hello), staleTime: 'static' }) }, beforeLoad: () => ({ hello: 'world' }), }) @@ -80,7 +80,7 @@ import { createFileRoute } from '@tanstack/react-router' export const Route = createFileRoute('/path')({ beforeLoad: () => ({ hello: 'world' }), loader: async ({ context }) => { - await context.queryClient.ensureQueryData(getQueryOptions(context.hello)) + await context.queryClient.query({ ...getQueryOptions(context.hello), staleTime: 'static' }) }, }) ``` @@ -98,7 +98,7 @@ import { createFileRoute } from '@tanstack/solid-router' export const Route = createFileRoute('/path')({ beforeLoad: () => ({ hello: 'world' }), loader: async ({ context }) => { - await context.queryClient.ensureQueryData(getQueryOptions(context.hello)) + await context.queryClient.query({ ...getQueryOptions(context.hello), staleTime: 'static' }) }, }) ``` diff --git a/docs/router/guide/deferred-data-loading.md b/docs/router/guide/deferred-data-loading.md index 9956542ebd3..ae9ad30ddcd 100644 --- a/docs/router/guide/deferred-data-loading.md +++ b/docs/router/guide/deferred-data-loading.md @@ -95,10 +95,10 @@ import { slowDataOptions, fastDataOptions } from '~/api/query-options' export const Route = createFileRoute('/posts/$postId')({ loader: async ({ context: { queryClient } }) => { // Kick off the fetching of some slower data, but do not await it - queryClient.prefetchQuery(slowDataOptions()) + void queryClient.query(slowDataOptions()).catch(noop) // Fetch and await some data that resolves quickly - await queryClient.ensureQueryData(fastDataOptions()) + await queryClient.query({...fastDataOptions(), staleTime: 'static') }, }) ``` @@ -113,10 +113,10 @@ import { slowDataOptions, fastDataOptions } from '~/api/query-options' export const Route = createFileRoute('/posts/$postId')({ loader: async ({ context: { queryClient } }) => { // Kick off the fetching of some slower data, but do not await it - queryClient.prefetchQuery(slowDataOptions()) + void queryClient.query(slowDataOptions()).catch(noop) // Fetch and await some data that resolves quickly - await queryClient.ensureQueryData(fastDataOptions()) + await queryClient.query({...fastDataOptions(), staleTime: 'static') }, }) ``` diff --git a/docs/router/guide/external-data-loading.md b/docs/router/guide/external-data-loading.md index a636bdfd789..7693c64ed3b 100644 --- a/docs/router/guide/external-data-loading.md +++ b/docs/router/guide/external-data-loading.md @@ -82,7 +82,7 @@ const postsQueryOptions = queryOptions({ export const Route = createFileRoute('/posts')({ // Use the `loader` option to ensure that the data is loaded - loader: () => queryClient.ensureQueryData(postsQueryOptions), + loader: () => queryClient.query({...postsQueryOptions, staleTime: 'static'), component: () => { // Read the data from the cache and subscribe to updates const { @@ -106,7 +106,7 @@ When an error occurs while using `suspense` with `TanStack Query`, you need to l ```tsx export const Route = createFileRoute('/')({ - loader: () => queryClient.ensureQueryData(postsQueryOptions), + loader: () => queryClient.query({...postsQueryOptions, staleTime: 'static' }), errorComponent: ({ error, reset }) => { const router = useRouter() const queryErrorResetBoundary = useQueryErrorResetBoundary() diff --git a/docs/router/guide/router-context.md b/docs/router/guide/router-context.md index 5fc4001010f..6a40531af97 100644 --- a/docs/router/guide/router-context.md +++ b/docs/router/guide/router-context.md @@ -278,9 +278,10 @@ Then, in your route: export const Route = createFileRoute('/todos')({ component: Todos, loader: async ({ context }) => { - await context.queryClient.ensureQueryData({ + await context.queryClient.query({ queryKey: ['todos', { userId: user.id }], queryFn: fetchTodos, + staleTime: 'static' }) }, }) diff --git a/docs/router/guide/type-safety.md b/docs/router/guide/type-safety.md index 2adffc58c56..4ffedcf51ad 100644 --- a/docs/router/guide/type-safety.md +++ b/docs/router/guide/type-safety.md @@ -137,12 +137,12 @@ As your application scales, TypeScript check times will naturally increase. Ther ### Only infer types you need -A great pattern with client side data caches (TanStack Query, etc.) is to prefetch data. For example with TanStack Query you might have a route which calls `queryClient.ensureQueryData` in a `loader`. +A great pattern with client side data caches (TanStack Query, etc.) is to prefetch data. For example with TanStack Query you might have a route which calls `queryClient.query` in a `loader`. ```tsx export const Route = createFileRoute('/posts/$postId/deep')({ loader: ({ context: { queryClient }, params: { postId } }) => - queryClient.ensureQueryData(postQueryOptions(postId)), + queryClient.query({ ...postQueryOptions(postId), staleTime: 'static' }), component: PostDeepComponent, }) @@ -159,7 +159,7 @@ This may look fine and for small route trees and you may not notice any TS perfo ```tsx export const Route = createFileRoute('/posts/$postId/deep')({ loader: async ({ context: { queryClient }, params: { postId } }) => { - await queryClient.ensureQueryData(postQueryOptions(postId)) + await queryClient.query({ ...postQueryOptions(postId), staleTime: 'static' }) }, component: PostDeepComponent, }) diff --git a/docs/router/how-to/setup-testing.md b/docs/router/how-to/setup-testing.md index 72f40032cfd..2ac7a2e54e0 100644 --- a/docs/router/how-to/setup-testing.md +++ b/docs/router/how-to/setup-testing.md @@ -651,9 +651,10 @@ describe('React Query Integration', () => { path: '/posts', component: PostsList, loader: ({ context: { queryClient } }) => - queryClient.ensureQueryData({ + queryClient.query({ queryKey: ['posts'], queryFn: mockFetchPosts, + staleTime: 'static' }), }) diff --git a/docs/router/integrations/query.md b/docs/router/integrations/query.md index 22fbb927c8f..f6802b87baa 100644 --- a/docs/router/integrations/query.md +++ b/docs/router/integrations/query.md @@ -118,7 +118,7 @@ const postsQuery = queryOptions({ export const Route = createFileRoute('/posts')({ // Ensure the data is in the cache before render - loader: ({ context }) => context.queryClient.ensureQueryData(postsQuery), + loader: ({ context }) => context.queryClient.query({...postsQuery, staleTime: 'static' }), component: PostsPage, }) @@ -133,7 +133,7 @@ function PostsPage() { ### Prefetching and streaming -You can also prefetch with `fetchQuery` or `ensureQueryData` in a loader without consuming the data in a component. If you return the promise directly from the loader, it will be awaited and thus block the SSR request until the query finishes. If you don't await the promise nor return it, the query will be started on the server and will be streamed to the client without blocking the SSR request. +You can also prefetch with `query` in a loader without consuming the data in a component. If you return the promise directly from the loader, it will be awaited and thus block the SSR request until the query finishes. If you don't await the promise nor return it, the query will be started on the server and will be streamed to the client without blocking the SSR request. diff --git a/docs/start/framework/react/comparison.md b/docs/start/framework/react/comparison.md index b68a1cc08e7..0fa28d8fd09 100644 --- a/docs/start/framework/react/comparison.md +++ b/docs/start/framework/react/comparison.md @@ -168,7 +168,7 @@ const postQueryOptions = (postId: string) => export const Route = createFileRoute('/posts/$postId')({ loader: ({ context, params }) => - context.queryClient.ensureQueryData(postQueryOptions(params.postId)), + context.queryClient.query({ ...postQueryOptions(params.postId), staleTime: `static` }), }) function Post() {