move query integration into a separate package

also renamed init function

Author: schiller-manuel

examples/react/start-basic-react-query/src/router.tsx

@@ -1,27 +1,26 @@
 import { QueryClient } from '@tanstack/react-query'
 import { createRouter as createTanStackRouter } from '@tanstack/react-router'
-import { routerWithQueryClient } from '@tanstack/react-router-ssr-query'
+import { setupRouterSsrQueryIntegration } from '@tanstack/react-router-ssr-query'
 import { routeTree } from './routeTree.gen'
 import { DefaultCatchBoundary } from './components/DefaultCatchBoundary'
 import { NotFound } from './components/NotFound'
 
-// NOTE: Most of the integration code found here is experimental and will
-// definitely end up in a more streamlined API in the future. This is just
-// to show what's possible with the current APIs.
-
 export function createRouter() {
   const queryClient = new QueryClient()
 
-  return routerWithQueryClient(
-    createTanStackRouter({
-      routeTree,
-      context: { queryClient },
-      defaultPreload: 'intent',
-      defaultErrorComponent: DefaultCatchBoundary,
-      defaultNotFoundComponent: () => <NotFound />,
-    }),
+  const router = createTanStackRouter({
+    routeTree,
+    context: { queryClient },
+    defaultPreload: 'intent',
+    defaultErrorComponent: DefaultCatchBoundary,
+    defaultNotFoundComponent: () => <NotFound />,
+  })
+  setupRouterSsrQueryIntegration({
+    router,
     queryClient,
-  )
+  })
+
+  return router
 }
 
 declare module '@tanstack/react-router' {

package.json

@@ -40,6 +40,7 @@
     "@playwright/test": "^1.52.0",
     "@tanstack/config": "^0.16.1",
     "@tanstack/react-query": "5.66.0",
+    "@tanstack/query-core": "5.66.0",
     "@types/node": "^22.10.2",
     "@types/react": "^19.0.8",
     "@types/react-dom": "^19.0.3",
@@ -80,7 +81,8 @@
       "eslint": "$eslint",
       "vite": "$vite",
       "@playwright/test": "$@playwright/test",
-      "@tanstack/react-query": "5.66.0",
+      "@tanstack/react-query": "$@tanstack/react-query",
+      "@tanstack/query-core": "$@tanstack/query-core",
       "use-sync-external-store": "1.2.2",
       "@tanstack/history": "workspace:*",
       "@tanstack/router-core": "workspace:*",
@@ -94,6 +96,7 @@
       "@tanstack/virtual-file-routes": "workspace:*",
       "@tanstack/router-plugin": "workspace:*",
       "@tanstack/router-vite-plugin": "workspace:*",
+      "@tanstack/router-ssr-query-core": "workspace:*",
       "@tanstack/react-router-ssr-query": "workspace:*",
       "@tanstack/zod-adapter": "workspace:*",
       "@tanstack/valibot-adapter": "workspace:*",

packages/react-router-ssr-query/package.json

@@ -63,19 +63,21 @@
   "engines": {
     "node": ">=12"
   },
+  "dependencies": {
+    "@tanstack/router-ssr-query-core": "workspace:^"
+  },
   "devDependencies": {
     "@vitejs/plugin-react": "^4.3.4",
     "react": ">=19",
     "react-dom": ">=19",
-    "@tanstack/router-core": "workspace:^",
     "@tanstack/react-router": "workspace:^",
-    "@tanstack/react-query": ">=5.66.0"
+    "@tanstack/react-query": ">=5.49.0"
   },
   "peerDependencies": {
     "react": ">=18.0.0 || >=19.0.0",
     "react-dom": ">=18.0.0 || >=19.0.0",
-    "@tanstack/router-core": ">=1.114.7",
-    "@tanstack/react-router": ">=1.43.2",
+    "@tanstack/query-core": ">=5.49.0",
+    "@tanstack/react-router": ">=1.127.0",
     "@tanstack/react-query": ">=5.49.2"
   }
 }

packages/react-router-ssr-query/src/index.tsx

@@ -1,209 +1,35 @@
 import { Fragment } from 'react'
-import {
-  QueryClientProvider,
-  dehydrate as queryDehydrate,
-  hydrate as queryHydrate,
-} from '@tanstack/react-query'
-import { isRedirect } from '@tanstack/router-core'
-import '@tanstack/router-core/ssr/client'
+import { QueryClientProvider } from '@tanstack/react-query'
 import type { AnyRouter } from '@tanstack/react-router'
-import type {
-  QueryClient,
-  DehydratedState as QueryDehydratedState,
-} from '@tanstack/react-query'
-
-type AdditionalOptions = {
-  WrapProvider?: (props: { children: any }) => React.JSX.Element
-  /**
-   * If `true`, the QueryClient will handle errors thrown by `redirect()` inside of mutations and queries.
-   *
-   * @default true
-   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/api/router/redirectFunction)
-   */
-  handleRedirects?: boolean
-}
+import {
+  RouterSsrQueryOptions,
+  setupCoreRouterSsrQueryIntegration,
+} from '@tanstack/router-ssr-query-core'
 
-type DehydratedRouterQueryState = {
-  dehydratedQueryClient: QueryDehydratedState
-  queryStream: ReadableStream<QueryDehydratedState>
-}
-export type ValidateRouter<TRouter extends AnyRouter> =
-  NonNullable<TRouter['options']['context']> extends {
-    queryClient: QueryClient
+export type Options<TRouter extends AnyRouter> =
+  RouterSsrQueryOptions<TRouter> & {
+    WrapProvider?: (props: { children: any }) => React.JSX.Element
   }
-    ? TRouter
-    : never
 
-export function routerWithQueryClient<TRouter extends AnyRouter>(
-  router: ValidateRouter<TRouter>,
-  queryClient: QueryClient,
-  additionalOpts?: AdditionalOptions,
-): TRouter {
-  const ogOptions = router.options
+export function setupRouterSsrQueryIntegration<TRouter extends AnyRouter>(
+  opts: Options<TRouter>,
+) {
+  setupCoreRouterSsrQueryIntegration(opts)
 
-  router.options = {
-    ...router.options,
-    context: {
-      ...ogOptions.context,
-      // Pass the query client to the context, so we can access it in loaders
-      queryClient,
-    },
-    // Wrap the app in a QueryClientProvider
+  const ogOptions = opts.router.options
+
+  opts.router.options = {
+    ...ogOptions,
     Wrap: ({ children }) => {
-      const OuterWrapper = additionalOpts?.WrapProvider || Fragment
+      const OuterWrapper = opts?.WrapProvider || Fragment
       const OGWrap = ogOptions.Wrap || Fragment
       return (
         <OuterWrapper>
-          <QueryClientProvider client={queryClient}>
+          <QueryClientProvider client={opts.queryClient}>
             <OGWrap>{children}</OGWrap>
           </QueryClientProvider>
         </OuterWrapper>
       )
     },
   }
-
-  if (router.isServer) {
-    const queryStream = createPushableStream()
-
-    router.options.dehydrate =
-      async (): Promise<DehydratedRouterQueryState> => {
-        const ogDehydrated = await ogOptions.dehydrate?.()
-        const dehydratedQueryClient = queryDehydrate(queryClient)
-
-        router.serverSsr!.onRenderFinished(() => queryStream.close())
-
-        const dehydratedRouter = {
-          ...ogDehydrated,
-          // When critical data is dehydrated, we also dehydrate the query client
-          dehydratedQueryClient,
-          // prepare the stream for queries coming up during rendering
-          queryStream: queryStream.stream,
-        }
-
-        return dehydratedRouter
-      }
-
-    const ogClientOptions = queryClient.getDefaultOptions()
-    queryClient.setDefaultOptions({
-      ...ogClientOptions,
-      dehydrate: {
-        shouldDehydrateQuery: () => true,
-        ...ogClientOptions.dehydrate,
-      },
-    })
-
-    queryClient.getQueryCache().subscribe((event) => {
-      if (event.type === 'added') {
-        // before rendering starts, we do not stream individual queries
-        // instead we dehydrate the entire query client in router's dehydrate()
-        if (!router.serverSsr!.isDehydrated()) {
-          return
-        }
-        if (queryStream.isClosed()) {
-          console.warn(
-            `tried to stream query ${event.query.queryHash} after stream was already closed`,
-          )
-          return
-        }
-        queryStream.enqueue(
-          queryDehydrate(queryClient, {
-            shouldDehydrateQuery: (query) => {
-              if (query.queryHash === event.query.queryHash) {
-                return (
-                  ogClientOptions.dehydrate?.shouldDehydrateQuery?.(query) ??
-                  true
-                )
-              }
-              return false
-            },
-          }),
-        )
-      }
-    })
-    // on the client
-  } else {
-    router.options.hydrate = async (dehydrated: DehydratedRouterQueryState) => {
-      await ogOptions.hydrate?.(dehydrated)
-      // On the client, hydrate the query client with the dehydrated data
-      queryHydrate(queryClient, dehydrated.dehydratedQueryClient)
-
-      const reader = dehydrated.queryStream.getReader()
-      reader
-        .read()
-        .then(async function handle({ done, value }) {
-          queryHydrate(queryClient, value)
-          if (done) {
-            return
-          }
-          const result = await reader.read()
-          return handle(result)
-        })
-        .catch((err) => {
-          console.error('Error reading query stream:', err)
-        })
-    }
-    if (additionalOpts?.handleRedirects ?? true) {
-      const ogMutationCacheConfig = queryClient.getMutationCache().config
-      queryClient.getMutationCache().config = {
-        ...ogMutationCacheConfig,
-        onError: (error, _variables, _context, _mutation) => {
-          if (isRedirect(error)) {
-            error.options._fromLocation = router.state.location
-            return router.navigate(router.resolveRedirect(error).options)
-          }
-
-          return ogMutationCacheConfig.onError?.(
-            error,
-            _variables,
-            _context,
-            _mutation,
-          )
-        },
-      }
-
-      const ogQueryCacheConfig = queryClient.getQueryCache().config
-      queryClient.getQueryCache().config = {
-        ...ogQueryCacheConfig,
-        onError: (error, _query) => {
-          if (isRedirect(error)) {
-            error.options._fromLocation = router.state.location
-            return router.navigate(router.resolveRedirect(error).options)
-          }
-
-          return ogQueryCacheConfig.onError?.(error, _query)
-        },
-      }
-    }
-  }
-
-  return router
-}
-
-type PushableStream = {
-  stream: ReadableStream
-  enqueue: (chunk: unknown) => void
-  close: () => void
-  isClosed: () => boolean
-  error: (err: unknown) => void
-}
-
-function createPushableStream(): PushableStream {
-  let controllerRef: ReadableStreamDefaultController
-  const stream = new ReadableStream({
-    start(controller) {
-      controllerRef = controller
-    },
-  })
-  let _isClosed = false
-
-  return {
-    stream,
-    enqueue: (chunk) => controllerRef.enqueue(chunk),
-    close: () => {
-      controllerRef.close()
-      _isClosed = true
-    },
-    isClosed: () => _isClosed,
-    error: (err: unknown) => controllerRef.error(err),
-  }
 }

packages/router-ssr-query-core/README.md

@@ -0,0 +1,5 @@
+<img src="https://static.scarf.sh/a.png?x-pxid=d988eb79-b0fc-4a2b-8514-6a1ab932d188" />
+
+# TanStack Router Core
+
+See [https://tanstack.com/router](https://tanstack.com/router) for documentation.

packages/router-ssr-query-core/eslint.config.js

@@ -0,0 +1,14 @@
+// @ts-check
+
+import rootConfig from '../../eslint.config.js'
+
+export default [
+  ...rootConfig,
+  {
+    files: ['src/**/*.{ts,tsx}', 'tests/**/*.{ts,tsx}'],
+    rules: {
+      'unused-imports/no-unused-vars': 'off',
+      '@typescript-eslint/no-unnecessary-condition': 'off',
+    },
+  },
+]