@tanstack/react-router 1.160.0 → 1.161.1

package/dist/llms/rules/setup-and-architecture.js

@@ -144,32 +144,22 @@ Enough overview, there's so much more to do with TanStack Router. Hit that next
 
 The fastest way to get started with TanStack Router is to scaffold a new project. Just run:
 
-[//]: # 'createAppCommand'
+<!-- ::start:tabs variant="package-managers" mode="local-install" -->
 
-\`\`\`sh
-npx create-tsrouter-app@latest
-\`\`\`
+react: create-tsrouter-app@latest
+solid: create-tsrouter-app@latest --framework solid
 
-[//]: # 'createAppCommand'
+<!-- ::end:tabs -->
 
 The CLI will guide you through a short series of prompts to customize your setup, including options for:
 
-[//]: # 'CLIPrompts'
-
 - File-based or code-based route configuration
 - TypeScript support
 - Tailwind CSS integration
 - Toolchain setup
 - Git initialization
 
-[//]: # 'CLIPrompts'
-
-Once complete, a new React project will be generated with TanStack Router installed and ready to use:
-
-\`\`\`sh
-cd your-project-name
-npm run dev
-\`\`\`
+Once complete, a new project will be generated with TanStack Router installed and ready to use.
 
 > [!TIP]
 > For full details on available options and templates, visit the [\`create-tsrouter-app\` documentation](https://github.com/TanStack/create-tsrouter-app/tree/main/cli/create-tsrouter-app).
@@ -182,32 +172,25 @@ TanStack Router supports both file-based and code-based route configurations. Yo
 
 The file-based approach is the recommended option for most projects. It automatically creates routes based on your file structure, giving you the best mix of performance, simplicity, and developer experience.
 
-[//]: # 'createAppCommandFileBased'
+<!-- ::start:tabs variant="package-manager" mode="local-install" -->
 
-\`\`\`sh
-npx create-tsrouter-app@latest my-app --template file-router
-\`\`\`
+react: create-tsrouter-app@latest my-app --template file-router
+solid: create-tsrouter-app@latest my-app --framework solid --template file-router
 
-[//]: # 'createAppCommandFileBased'
+<!-- ::end:tabs -->
 
 ### Code-Based Route Configuration
 
 If you prefer to define routes programmatically, you can use the code-based route configuration. This approach gives you full control over routing logic.
 
-[//]: # 'createAppCommandCodeBased'
+<!-- ::start:tabs variant="package-manager" mode="local-install" -->
 
-\`\`\`sh
-npx create-tsrouter-app@latest my-app
-\`\`\`
-
-[//]: # 'createAppCommandCodeBased'
+react: create-tsrouter-app@latest my-app
+solid: create-tsrouter-app@latest my-app --framework solid
 
-With either approach, navigate to your project directory and start the development server:
+<!-- ::end:tabs -->
 
-\`\`\`sh
-cd my-app
-npm run dev
-\`\`\`
+With either approach, navigate to your project directory and start the development server.
 
 ## Existing Project
 
@@ -217,12 +200,18 @@ If you have an existing React project and want to add TanStack Router to it, you
 
 Before installing TanStack Router, please ensure your project meets the following requirements:
 
-[//]: # 'Requirements'
+<!-- ::start:framework -->
+
+# React
 
 - \`react\` v18 or later with \`createRoot\` support.
 - \`react-dom\` v18 or later.
 
-[//]: # 'Requirements'
+# Solid
+
+- \`solid-js\` v1.x.x
+
+<!-- ::end:framework -->
 
 > [!NOTE]
 > Using TypeScript (\`v5.3.x or higher\`) is recommended for the best development experience, though not strictly required. We aim to support the last 5 minor versions of TypeScript, but using the latest version will help avoid potential issues.
@@ -233,25 +222,18 @@ TanStack Router is currently only compatible with React (with ReactDOM) and Soli
 
 To install TanStack Router in your project, run the following command using your preferred package manager:
 
-[//]: # 'installCommand'
-
-\`\`\`sh
-npm install @tanstack/react-router
-# or
-pnpm add @tanstack/react-router
-#or
-yarn add @tanstack/react-router
-# or
-bun add @tanstack/react-router
-# or
-deno add npm:@tanstack/react-router
-\`\`\`
+<!-- ::start:tabs variant="package-managers" -->
+
+react: @tanstack/react-router
+solid: @tanstack/solid-router
 
-[//]: # 'installCommand'
+<!-- ::end:tabs -->
 
 Once installed, you can verify the installation by checking your \`package.json\` file for the dependency.
 
-[//]: # 'packageJson'
+<!-- ::start:framework -->
+
+# React
 
 \`\`\`json
 {
@@ -261,7 +243,17 @@ Once installed, you can verify the installation by checking your \`package.json\
 }
 \`\`\`
 
-[//]: # 'packageJson'
+# Solid
+
+\`\`\`json
+{
+  "dependencies": {
+    "@tanstack/solid-router": "^x.x.x"
+  }
+}
+\`\`\`
+
+<!-- ::end:framework -->
 
 # Decisions on Developer Experience
 
@@ -277,9 +269,12 @@ And they are all valid questions. For the most part, people are used to using ro
 
 But TanStack Router is different. It's not your average routing library. It's not your average state management library. It's not your average anything.
 
+> [!TIP]
+> The examples in this guide use React for components and code snippets, but the same principles apply to Solid. The only difference is in the syntax and API of the framework, but the underlying concepts and design decisions are the same.
+
 ## TanStack Router's origin story
 
-It's important to remember that TanStack Router's origins stem from [Nozzle.io](https://nozzle.io)'s need for a client-side routing solution that offered a first-in-class _URL Search Parameters_ experience without compromising on the **_type-safety_** that was required to power its complex dashboards.
+It's important to remember that TanStack Router's origins stem from [Nozzle.io](https://nozzle.io?utm_source=tanstack)'s need for a client-side routing solution that offered a first-in-class _URL Search Parameters_ experience without compromising on the **_type-safety_** that was required to power its complex dashboards.
 
 And so, from TanStack Router's very inception, every facet of its design was meticulously thought out to ensure that its type-safety and developer experience were second to none.
 
@@ -511,48 +506,66 @@ When you begin your TanStack Router journey, you'll want these devtools by your
 
 The devtools are a separate package that you need to install:
 
-\`\`\`sh
-npm install @tanstack/react-router-devtools
-\`\`\`
+<!-- ::start:tabs variant="package-manager" -->
 
-or
+react: @tanstack/react-router-devtools
+solid: @tanstack/solid-router-devtools
 
-\`\`\`sh
-pnpm add @tanstack/react-router-devtools
-\`\`\`
+<!-- ::end:tabs -->
 
-or
+## Import the Devtools
 
-\`\`\`sh
-yarn add @tanstack/react-router-devtools
-\`\`\`
+<!-- ::start:framework -->
 
-or
+# React
 
-\`\`\`sh
-bun add @tanstack/react-router-devtools
+\`\`\`tsx
+import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
 \`\`\`
 
-## Import the Devtools
+# Solid
 
-\`\`\`js
-import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
+\`\`\`tsx
+import { TanStackRouterDevtools } from '@tanstack/solid-router-devtools'
 \`\`\`
 
+<!-- ::end:framework -->
+
 ## Using Devtools in production
 
 The Devtools, if imported as \`TanStackRouterDevtools\` will not be shown in production. If you want to have devtools in an environment with \`process.env.NODE_ENV === 'production'\`, use instead \`TanStackRouterDevtoolsInProd\`, which has all the same options:
 
+<!-- ::start:framework -->
+
+# React
+
 \`\`\`tsx
 import { TanStackRouterDevtoolsInProd } from '@tanstack/react-router-devtools'
 \`\`\`
 
-## Using inside of the \`RouterProvider\`
+# Solid
+
+\`\`\`tsx
+import { TanStackRouterDevtoolsInProd } from '@tanstack/solid-router-devtools'
+\`\`\`
+
+<!-- ::end:framework -->
+
+## Using the Devtools in the root route
 
 The easiest way for the devtools to work is to render them inside of your root route (or any other route). This will automatically connect the devtools to the router instance.
 
-\`\`\`tsx
-const rootRoute = createRootRoute({
+<!-- ::start:framework -->
+
+# React
+
+<!-- ::start:tabs variant="files" -->
+
+\`\`\`tsx title="src/routes/__root.tsx"
+import { createRootRoute, Outlet } from '@tanstack/react-router'
+import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
+
+export const Route = createRootRoute({
   component: () => (
     <>
       <Outlet />
@@ -560,24 +573,53 @@ const rootRoute = createRootRoute({
     </>
   ),
 })
+\`\`\`
 
-const routeTree = rootRoute.addChildren([
-  // ... other routes
-])
+<!-- ::end:tabs -->
 
-const router = createRouter({
-  routeTree,
-})
+# Solid
 
-function App() {
-  return <RouterProvider router={router} />
-}
+<!-- ::start:tabs variant="files" -->
+
+\`\`\`tsx title="src/routes/__root.tsx"
+import { createRootRoute, Outlet } from '@tanstack/solid-router'
+import { TanStackRouterDevtools } from '@tanstack/solid-router-devtools'
+
+export const Route = createRootRoute({
+  component: () => (
+    <>
+      <Outlet />
+      <TanStackRouterDevtools />
+    </>
+  ),
+})
 \`\`\`
 
+<!-- ::end:tabs -->
+
+<!-- ::end:framework -->
+
 ## Manually passing the Router Instance
 
 If rendering the devtools inside of the \`RouterProvider\` isn't your cup of tea, a \`router\` prop for the devtools accepts the same \`router\` instance you pass to the \`Router\` component. This makes it possible to place the devtools anywhere on the page, not just inside the provider:
 
+<!-- ::start:framework -->
+
+# React
+
+\`\`\`tsx
+function App() {
+  return (
+    <>
+      <RouterProvider router={router} />
+      <TanStackRouterDevtools router={router} />
+    </>
+  )
+}
+\`\`\`
+
+# Solid
+
 \`\`\`tsx
 function App() {
   return (
@@ -589,25 +631,44 @@ function App() {
 }
 \`\`\`
 
+<!-- ::end:framework -->
+
 ## Floating Mode
 
 Floating Mode will mount the devtools as a fixed, floating element in your app and provide a toggle in the corner of the screen to show and hide the devtools. This toggle state will be stored and remembered in localStorage across reloads.
 
-Place the following code as high in your React app as you can. The closer it is to the root of the page, the better it will work!
+Place the following code as high in your app as you can. The closer it is to the root of the page, the better it will work!
 
-\`\`\`js
-import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
+<!-- ::start:framework -->
+
+# React
+
+\`\`\`tsx
+function App() {
+  return (
+    <>
+      <RouterProvider router={router} />
+      <TanStackRouterDevtools initialIsOpen={false} />
+    </>
+  )
+}
+\`\`\`
+
+# Solid
 
+\`\`\`tsx
 function App() {
   return (
     <>
-      <Router />
+      <RouterProvider router={router} />
       <TanStackRouterDevtools initialIsOpen={false} />
     </>
   )
 }
 \`\`\`
 
+<!-- ::end:framework -->
+
 ### Devtools Options
 
 - \`router: Router\`
@@ -635,32 +696,63 @@ function App() {
 
 To control the position of the devtools, import the \`TanStackRouterDevtoolsPanel\`:
 
-\`\`\`js
+<!-- ::start:framework -->
+
+# React
+
+\`\`\`tsx
 import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'
 \`\`\`
 
+# Solid
+
+\`\`\`tsx
+import { TanStackRouterDevtoolsPanel } from '@tanstack/solid-router-devtools'
+\`\`\`
+
+<!-- ::end:framework -->
+
 It can then be attached to provided shadow DOM target:
 
-\`\`\`js
+<!-- ::start:framework -->
+
+# React
+
+\`\`\`tsx
 <TanStackRouterDevtoolsPanel
   shadowDOMTarget={shadowContainer}
   router={router}
 />
 \`\`\`
 
+# Solid
+
+\`\`\`tsx
+<TanStackRouterDevtoolsPanel
+  shadowDOMTarget={shadowContainer}
+  router={router}
+/>
+\`\`\`
+
+<!-- ::end:framework -->
+
 Click [here](https://tanstack.com/router/latest/docs/framework/react/examples/basic-devtools-panel) to see a live example of this in StackBlitz.
 
 ## Embedded Mode
 
 Embedded Mode will embed the devtools as a regular component in your application. You can style it however you'd like after that!
 
-\`\`\`js
+<!-- ::start:framework -->
+
+# React
+
+\`\`\`tsx
 import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'
 
 function App() {
   return (
     <>
-      <Router router={router} />
+      <RouterProvider router={router} />
       <TanStackRouterDevtoolsPanel
         router={router}
         style={styles}
@@ -671,14 +763,50 @@ function App() {
 }
 \`\`\`
 
+# Solid
+
+\`\`\`tsx
+import { TanStackRouterDevtoolsPanel } from '@tanstack/solid-router-devtools'
+
+function App() {
+  return (
+    <>
+      <RouterProvider router={router} />
+      <TanStackRouterDevtoolsPanel
+        router={router}
+        style={styles}
+        class={className}
+      />
+    </>
+  )
+}
+\`\`\`
+
+<!-- ::end:framework -->
+
 ### DevtoolsPanel Options
 
 - \`router: Router\`
   - The router instance to connect to.
-- \`style: StyleObject\`
+
+<!-- ::start:framework -->
+
+# React
+
+- \`style?: StyleObject\`
   - The standard React style object used to style a component with inline styles.
-- \`className: string\`
+- \`className?: string\`
   - The standard React className property used to style a component with classes.
+
+# Solid
+
+- \`style?: StyleObject\`
+  - The standard Solid style object used to style a component with inline styles.
+- \`class?: string\`
+  - The standard Solid class property used to style a component with classes.
+
+<!-- ::end:framework -->
+
 - \`isOpen?: boolean\`
   - A boolean variable indicating whether the panel is open or closed.
 - \`setIsOpen?: (isOpen: boolean) => void\`
@@ -716,7 +844,6 @@ You should commit this file into git so that other developers can use it to buil
 ## Can I conditionally render the Root Route component?
 
 No, the root route is always rendered as it is the entry point of your application.
-
 If you need to conditionally render a route's component, this usually means that the page content needs to be different based on some condition (e.g. user authentication). For this use case, you should use a [Layout Route](./routing/routing-concepts.md#layout-routes) or a [Pathless Layout Route](./routing/routing-concepts.md#pathless-layout-routes) to conditionally render the content.
 
 You can restrict access to these routes using a conditional check in the \`beforeLoad\` function of the route.
@@ -724,6 +851,10 @@ You can restrict access to these routes using a conditional check in the \`befor
 <details>
 <summary>What does this look like?</summary>
 
+<!-- ::start:framework -->
+
+# React
+
 \`\`\`tsx
 // src/routes/_pathless-layout.tsx
 import { createFileRoute, Outlet } from '@tanstack/react-router'
@@ -752,6 +883,38 @@ function PathlessLayoutRouteComponent() {
 }
 \`\`\`
 
+# Solid
+
+\`\`\`tsx
+// src/routes/_pathless-layout.tsx
+import { createFileRoute, Outlet } from '@tanstack/solid-router'
+import { isAuthenticated } from '../utils/auth'
+
+export const Route = createFileRoute('/_pathless-layout', {
+  beforeLoad: async () => {
+    // Check if the user is authenticated
+    const authed = await isAuthenticated()
+    if (!authed) {
+      // Redirect the user to the login page
+      return '/login'
+    }
+  },
+  component: PathlessLayoutRouteComponent,
+  // ...
+})
+
+function PathlessLayoutRouteComponent() {
+  return (
+    <div>
+      <h1>You are authed</h1>
+      <Outlet />
+    </div>
+  )
+}
+\`\`\`
+
+<!-- ::end:framework -->
+
 </details>
 
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-router",
-  "version": "1.160.0",
+  "version": "1.161.1",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -82,7 +82,7 @@
     "tiny-invariant": "^1.3.3",
     "tiny-warning": "^1.0.3",
     "@tanstack/history": "1.154.14",
-    "@tanstack/router-core": "1.160.0"
+    "@tanstack/router-core": "1.161.1"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",

package/src/Asset.tsx

@@ -1,6 +1,7 @@
 import * as React from 'react'
 import { isServer } from '@tanstack/router-core/isServer'
 import { useRouter } from './useRouter'
+import { useHydrated } from './ClientOnly'
 import type { RouterManagedTag } from '@tanstack/router-core'
 
 interface ScriptAttrs {
@@ -49,12 +50,24 @@ function Script({
   children?: string
 }) {
   const router = useRouter()
+  const hydrated = useHydrated()
   const dataScript =
     typeof attrs?.type === 'string' &&
     attrs.type !== '' &&
     attrs.type !== 'text/javascript' &&
     attrs.type !== 'module'
 
+  if (
+    process.env.NODE_ENV !== 'production' &&
+    attrs?.src &&
+    typeof children === 'string' &&
+    children.trim().length
+  ) {
+    console.warn(
+      '[TanStack Router] <Script> received both `src` and `children`. The `children` content will be ignored. Remove `children` or remove `src`.',
+    )
+  }
+
   React.useEffect(() => {
     if (dataScript) return
 
@@ -151,41 +164,56 @@ function Script({
     return undefined
   }, [attrs, children, dataScript])
 
-  if (!(isServer ?? router.isServer)) {
-    if (dataScript && typeof children === 'string') {
+  // --- Server rendering ---
+  if (isServer ?? router.isServer) {
+    if (attrs?.src) {
+      return <script {...attrs} suppressHydrationWarning />
+    }
+
+    if (typeof children === 'string') {
       return (
         <script
           {...attrs}
-          suppressHydrationWarning
           dangerouslySetInnerHTML={{ __html: children }}
+          suppressHydrationWarning
         />
       )
     }
 
-    const { src: _src, async: _async, defer: _defer, ...rest } = attrs || {}
-    // render an empty script on the client just to avoid hydration errors
-    return (
-      <script
-        suppressHydrationWarning
-        dangerouslySetInnerHTML={{ __html: '' }}
-        {...rest}
-      ></script>
-    )
+    return null
   }
 
-  if (attrs?.src && typeof attrs.src === 'string') {
-    return <script {...attrs} suppressHydrationWarning />
-  }
+  // --- Client rendering ---
 
-  if (typeof children === 'string') {
+  // Data scripts (e.g. application/ld+json) are rendered in the tree;
+  // the useEffect intentionally skips them.
+  if (dataScript && typeof children === 'string') {
     return (
       <script
         {...attrs}
-        dangerouslySetInnerHTML={{ __html: children }}
         suppressHydrationWarning
+        dangerouslySetInnerHTML={{ __html: children }}
       />
     )
   }
 
+  // During hydration (before useEffect has fired), render the script element
+  // to match the server-rendered HTML and avoid structural hydration mismatches.
+  // After hydration, return null — the useEffect handles imperative injection.
+  if (!hydrated) {
+    if (attrs?.src) {
+      return <script {...attrs} suppressHydrationWarning />
+    }
+    if (typeof children === 'string') {
+      return (
+        <script
+          {...attrs}
+          dangerouslySetInnerHTML={{ __html: children }}
+          suppressHydrationWarning
+        />
+      )
+    }
+  }
+
   return null
 }