Merge branch 'main' into start-head-api

.github/workflows/autofix.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/[email protected].1
+        uses: actions/[email protected].2
       - name: Setup Tools
         uses: tanstack/config/.github/setup@main
       - name: Fix formatting

.github/workflows/ci.yml

@@ -27,7 +27,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/[email protected].1
+        uses: actions/[email protected].2
         with:
           fetch-depth: 0
       - name: Start Nx Agents

.github/workflows/pr.yml

@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/[email protected].1
+        uses: actions/[email protected].2
         with:
           fetch-depth: 0
       - name: Start Nx Agents
@@ -40,7 +40,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/[email protected].1
+        uses: actions/[email protected].2
         with:
           fetch-depth: 0
       - name: Setup Tools

.gitignore

@@ -22,6 +22,7 @@ coverage
 
 # tests
 packages/router-generator/tests/**/*.gen.ts
+packages/router-generator/tests/**/*.gen.js
 
 # misc
 .DS_Store

docs/framework/react/api/router/LinkOptionsType.md

@@ -33,7 +33,7 @@ The `LinkOptions` object accepts/contains the following properties:
 
 ### `preload`
 
-- Type: `false | 'intent' | 'viewport'`
+- Type: `false | 'intent' | 'viewport' | 'render'`
 - Optional
 - If set, the link's preloading strategy will be set to this value.
 - See the [Preloading guide](../../guide/preloading.md) for more information.

docs/framework/react/api/router/RouterEventsType.md

@@ -25,6 +25,12 @@ type RouterEvents = {
     toLocation: ParsedLocation
     pathChanged: boolean
   }
+  onBeforeRouteMount: {
+    type: 'onBeforeRouteMount'
+    fromLocation: ParsedLocation
+    toLocation: ParsedLocation
+    pathChanged: boolean
+  }
 }
 ```
 
@@ -34,7 +40,7 @@ Once an event is emitted, the following properties will be present on the event
 
 ### `type` property
 
-- Type: `onBeforeLoad | onLoad | onResolved`
+- Type: `onBeforeLoad | onLoad | onBeforeRouteMount | onResolved`
 - The type of the event
 - This is useful for discriminating between events in a listener function.
 

docs/framework/react/api/router/RouterOptionsType.md

@@ -46,12 +46,13 @@ The `RouterOptions` type accepts an object with the following properties and met
 
 ### `defaultPreload` property
 
-- Type: `undefined | false | 'intent' | 'viewport'`
+- Type: `undefined | false | 'intent' | 'viewport' | 'render'`
 - Optional
 - Defaults to `false`
 - If `false`, routes will not be preloaded by default in any way.
 - If `'intent'`, routes will be preloaded by default when the user hovers over a link or a `touchstart` event is detected on a `<Link>`.
 - If `'viewport'`, routes will be preloaded by default when they are within the viewport of the browser.
+- If `'render'`, routes will be preloaded by default as soon as they are rendered in the DOM.
 
 ### `defaultPreloadDelay` property
 

docs/framework/react/api/router/RouterType.md

@@ -131,17 +131,17 @@ Navigates to a new location.
 
 Invalidates route matches by forcing their `beforeLoad` and `load` functions to be called again.
 
-- Type: `(opts?: {filter?: (d: MakeRouteMatch<TRouteTree>) => boolean}) => Promise<void>`
+- Type: `(opts?: {filter?: (d: MakeRouteMatchUnion<TRouter>) => boolean}) => Promise<void>`
 - This is useful any time your loader data might be out of date or stale. For example, if you have a route that displays a list of posts, and you have a loader function that fetches the list of posts from an API, you might want to invalidate the route matches for that route any time a new post is created so that the list of posts is always up-to-date.
 - if `filter` is not supplied, all matches will be invalidated
 - if `filter` is supplied, only matches for which `filter` returns `true` will be invalidated.
 - You might also want to invalidate the Router if you imperatively `reset` the router's `CatchBoundary` to trigger loaders again.
 
-### `.removeCachedMatches` method
+### `.clearCache` method
 
 Remove cached route matches.
 
-- Type: `(opts?: {filter?: (d: MakeRouteMatch<TRouteTree>) => boolean}) => void`
+- Type: `(opts?: {filter?: (d: MakeRouteMatchUnion<TRouter>) => boolean}) => void`
 - if `filter` is not supplied, all cached matches will be removed
 - if `filter` is supplied, only matches for which `filter` returns `true` will be removed.
 

docs/framework/react/api/router/stripSearchParamsFunction.md

@@ -7,7 +7,7 @@ title: Search middleware to strip search params
 
 ## stripSearchParams props
 
-The `retainSearchParams` accepts one of the following inputs:
+`stripSearchParams` accepts one of the following inputs:
 
 - `true`: if the search schema has no required params, `true` can be used to strip all search params
 - a list of keys of those search params that shall be removed; only keys of optional search params are allowed.

docs/framework/react/guide/code-splitting.md

@@ -185,7 +185,7 @@ Tada! 🎉
 When using the `autoCodeSplitting` feature, TanStack Router will automatically code split your route files based on the non-critical route configuration mentioned above.
 
 > [!IMPORTANT]
-> The automatic code-splitting feature is **ONLY** available when you are using file-based routing with one of our [supported bundlers](./file-based-routing.md#prerequisites).
+> The automatic code-splitting feature is **ONLY** available when you are using file-based routing with one of our [supported bundlers](./file-based-routing.md#installation).
 > This will **NOT** work if you are **only** using the CLI (`@tanstack/router-cli`).
 
 If this is your first time using TanStack Router, then you can skip the following steps and head over to [Enabling automatic code-splitting](#enabling-automatic-code-splitting). If you've already been using TanStack Router, then you might need to make some changes to your route files to enable automatic code-splitting.

docs/framework/react/guide/data-loading.md

@@ -78,7 +78,7 @@ The `loader` function receives a single object with the following properties:
 - `deps` - The object value returned from the `Route.loaderDeps` function. If `Route.loaderDeps` is not defined, an empty object will be provided instead.
 - `location` - The current location
 - `params` - The route's path params
-- `parentMatchPromise` - `Promise<void>` or `undefined`
+- `parentMatchPromise` - `Promise<RouteMatch>` (`undefined` for the root route)
 - `preload` - Boolean which is `true` when the route is being preloaded instead of loaded
 - `route` - The route itself
 

docs/framework/react/guide/file-based-routing.md

@@ -4,6 +4,9 @@ title: File-Based Routing
 
 Most of the TanStack Router documentation is written for file-based routing and is intended to help you understand in more detail how to configure file-based routing and the technical details behind how it works. While file-based routing is the preferred and recommended way to configure TanStack Router, you can also use [code-based routing](./code-based-routing.md) if you prefer.
 
+> [!NOTE]
+> 🧠 If you are already familiar with how file-based routing works and are looking for setup instructions, you can skip ahead to the [Installation](#installation) section. Or if you looking for the configuration options, skip ahead to the [Options](#options) section.
+
 ## What is File-Based Routing?
 
 File-based routing is a way to configure your routes using the filesystem. Instead of defining your route structure via code, you can define your routes using a series of files and directories that represent the route hierarchy of your application. This brings a number of benefits:
@@ -143,23 +146,21 @@ File-based routing requires that you follow a few simple file naming conventions
 - **`.lazy.tsx` File Type**
   - The `lazy` suffix can be used to code-split components for a route. For example, `blog.post.lazy.tsx` will be used as the component for the `blog.post` route.
 
-## Prerequisites
+## Installation
+
+To get started with file-based routing, you'll need to configure your project's bundler to use the TanStack Router Plugin or the TanStack Router CLI.
 
 To enable file-based routing, you'll need to be using React with a supported bundler. TanStack Router currently has support for the following bundlers:
 
-- Vite
-- Rspack/Rsbuild
-- Webpack
-- Esbuild
+- [Vite](#configuration-with-vite)
+- [Rspack/Rsbuild](#configuration-with-rspackrsbuild)
+- [Webpack](#configuration-with-webpack)
+- [Esbuild](#configuration-with-esbuild)
 - Others??? (let us know if you'd like to see support for a specific bundler)
 
-If your bundler is not yet supported, you can reach out to us on Discord or GitHub to let us know. Till then, fear not! You can still use the [`@tanstack/router-cli`](#configuration-with-the-tanstack-router-cli) package to generate your route tree file.
-
-## Installation
-
-To get started with file-based routing, you'll need to configure your project's bundler to use the TanStack Router Plugin or the TanStack Router CLI.
+When using using TanStack Router's file-based routing through one of the supported bundlers, our plugin will **automatically generate your route configuration through your bundler's dev and build processes**. It is the easiest way to use TanStack Router's route generation features.
 
-If you are using TanStack Router's file-based routing through a bundler, the plugin will **automatically generate your route configuration through your bundler's dev and build processes**. It is the easiest way to use TanStack Router's route generation features.
+If your bundler is not yet supported, you can reach out to us on Discord or GitHub to let us know. Till then, fear not! You can still use the [`@tanstack/router-cli`](#configuration-with-the-tanstack-router-cli) package to generate your route tree file.
 
 ### Configuration with Vite
 
@@ -192,6 +193,10 @@ Or, you can clone our [Quickstart Vite example](https://github.com/TanStack/rout
 > [!WARNING]
 > If you are using the older `@tanstack/router-vite-plugin` package, you can still continue to use it, as it will be aliased to the `@tanstack/router-plugin/vite` package. However, we would recommend using the `@tanstack/router-plugin` package directly.
 
+Now that you've added the plugin to your Vite configuration, you're all set to start using file-based routing with TanStack Router.
+
+You shouldn't forget to _ignore_ the generated route tree file. Head over to the [Ignoring the generated route tree file](#ignoring-the-generated-route-tree-file) section to learn more.
+
 ### Configuration with Rspack/Rsbuild
 
 To use file-based routing with **Rspack** or **Rsbuild**, you'll need to install the `@tanstack/router-plugin` package.
@@ -220,6 +225,10 @@ export default defineConfig({
 
 Or, you can clone our [Quickstart Rspack/Rsbuild example](https://github.com/TanStack/router/tree/main/examples/react/quickstart-rspack-file-based) and get started.
 
+Now that you've added the plugin to your Rspack/Rsbuild configuration, you're all set to start using file-based routing with TanStack Router.
+
+You shouldn't forget to _ignore_ the generated route tree file. Head over to the [Ignoring the generated route tree file](#ignoring-the-generated-route-tree-file) section to learn more.
+
 ### Configuration with Webpack
 
 To use file-based routing with **Webpack**, you'll need to install the `@tanstack/router-plugin` package.
@@ -241,6 +250,10 @@ export default {
 
 Or, you can clone our [Quickstart Webpack example](https://github.com/TanStack/router/tree/main/examples/react/quickstart-webpack-file-based) and get started.
 
+Now that you've added the plugin to your Webpack configuration, you're all set to start using file-based routing with TanStack Router.
+
+You shouldn't forget to _ignore_ the generated route tree file. Head over to the [Ignoring the generated route tree file](#ignoring-the-generated-route-tree-file) section to learn more.
+
 ### Configuration with Esbuild
 
 To use file-based routing with **Esbuild**, you'll need to install the `@tanstack/router-plugin` package.
@@ -263,6 +276,10 @@ export default {
 
 Or, you can clone our [Quickstart Esbuild example](https://github.com/TanStack/router/tree/main/examples/react/quickstart-esbuild-file-based) and get started.
 
+Now that you've added the plugin to your Esbuild configuration, you're all set to start using file-based routing with TanStack Router.
+
+You shouldn't forget to _ignore_ the generated route tree file. Head over to the [Ignoring the generated route tree file](#ignoring-the-generated-route-tree-file) section to learn more.
+
 ### Configuration with the TanStack Router CLI
 
 To use file-based routing with the TanStack Router CLI, you'll need to install the `@tanstack/router-cli` package.
@@ -284,6 +301,8 @@ Once installed, you'll need to amend your your scripts in your `package.json` fo
 }
 ```
 
+You shouldn't forget to _ignore_ the generated route tree file. Head over to the [Ignoring the generated route tree file](#ignoring-the-generated-route-tree-file) section to learn more.
+
 With the CLI installed, the following commands are made available via the `tsr` command
 
 #### Using the `generate` command
@@ -329,6 +348,26 @@ export default defineConfig({
 })
 ```
 
+### Ignoring the generated route tree file
+
+If your project is configured to use a linter and/or formatter, you may want to ignore the generated route tree file. This is this file is managed by TanStack Router and shouldn't and therefore shouldn't be changed by your linter or formatter.
+
+Here are some resources to help you ignore the generated route tree file:
+
+- Prettier - [https://prettier.io/docs/en/ignore.html#ignoring-files-prettierignore](https://prettier.io/docs/en/ignore.html#ignoring-files-prettierignore)
+- ESLint - [https://eslint.org/docs/latest/use/configure/ignore#ignoring-files](https://eslint.org/docs/latest/use/configure/ignore#ignoring-files)
+- Biome - [https://biomejs.dev/reference/configuration/#filesignore](https://biomejs.dev/reference/configuration/#filesignore)
+
+If you are using VSCode, you can also add the following to your `.vscode/settings.json` file to exclude the generated route tree file from the editor's file watcher:
+
+```json
+{
+  "files.watcherExclude": {
+    "**/routeTree.gen.ts": true
+  }
+}
+```
+
 ## Configuration
 
 File-based routing comes with some sane defaults that should work for most projects:
@@ -394,7 +433,6 @@ The following options are available for configuration via the `tsr.config.json`
   - Default:
   - ```
     [
-      '/* prettier-ignore-start */',
       '/* eslint-disable */',
       '// @ts-nocheck',
       '// noinspection JSUnusedGlobalSymbols'
@@ -403,13 +441,8 @@ The following options are available for configuration via the `tsr.config.json`
 
 - **`routeTreeFileFooter`**
   - (Optional) An array of strings to append to the generated route tree file content.
-  - Default:
-  - ```
-    [
-      '/* prettier-ignore-end */'
-    ]
-    ```
-- **`disableManifestGeneration**
+  - Default: `[]`
+- **`disableManifestGeneration`**
   - (Optional, **Defaults to `false`**) disables generating the route tree manifest
 
 ## Route Inclusion / Exclusion

docs/framework/react/guide/preloading.md

@@ -13,7 +13,8 @@ Preloading in TanStack Router is a way to load a route before the user actually
   - Preloading by **"viewport**" works by using the Intersection Observer API to preload the dependencies for the destination route when the `<Link>` component is in the viewport.
   - This strategy is useful for preloading routes that are below the fold or off-screen.
 - Render
-  - **Coming soon!**
+  - Preloading by **"render"** works by preloading the dependencies for the destination route as soon as the `<Link>` component is rendered in the DOM.
+  - This strategy is useful for preloading routes that are always needed.
 
 ## How long does preloaded data stay in memory?
 

docs/framework/react/guide/search-params.md

@@ -302,7 +302,6 @@ export const Route = createFileRoute('/shop/products/')({
 When using [ArkType](https://arktype.io/) an adapter is not needed to ensure the correct `input` and `output` types are used for navigation and reading search params. This is because [ArkType](https://arktype.io/) implements [Standard Schema](https://github.com/standard-schema/standard-schema)
 
 ```tsx
-import { arkTypeSearchValidator } from '@tanstack/router-arktype-adapter'
 import { createFileRoute } from '@tanstack/react-router'
 import { type } from 'arktype'
 

docs/framework/react/migrate-from-react-location.md

@@ -57,7 +57,7 @@ export default defineConfig({
 })
 ```
 
-However, if your application does not use Vite, you use one of our other [supported bundlers](./guide/file-based-routing.md#prerequisites), or you can use the `@tanstack/router-cli` package to watch for changes in your routes files and automatically update the routes configuration.
+However, if your application does not use Vite, you use one of our other [supported bundlers](./guide/file-based-routing.md#installation), or you can use the `@tanstack/router-cli` package to watch for changes in your routes files and automatically update the routes configuration.
 
 ### Step 3: Add the file-based configuration file to your project
 

docs/framework/react/start/getting-started.md

@@ -53,7 +53,7 @@ npm i @tanstack/start @tanstack/react-router vinxi
 You'll also need React and the Vite React plugin, so install them too:
 
 ```shell
-npm i react react-dom @vitejs/plugin-react
+npm i react react-dom; npm i -D @vitejs/plugin-react
 ```
 
 and some TypeScript:
@@ -66,15 +66,15 @@ npm i -D typescript @types/react @types/react-dom
 
 We'll then update our `package.json` to reference the new Vinxi entry point and set `"type": "module"`:
 
-```jsonc
+```json
 {
   // ...
   "type": "module",
   "scripts": {
     "dev": "vinxi dev",
     "build": "vinxi build",
-    "start": "vinxi start",
-  },
+    "start": "vinxi start"
+  }
 }
 ```
 
@@ -195,10 +195,13 @@ Finally, we need to create the root of our application. This is the entry point
 
 ```tsx
 // app/routes/__root.tsx
-import { createRootRoute } from '@tanstack/react-router'
-import { Outlet, ScrollRestoration } from '@tanstack/react-router'
+import {
+  Outlet,
+  ScrollRestoration,
+  createRootRoute,
+} from '@tanstack/react-router'
 import { Body, Head, Html, Meta, Scripts } from '@tanstack/start'
-import * as React from 'react'
+import type { ReactNode } from 'react'
 
 export const Route = createRootRoute({
   head: () => ({
@@ -226,7 +229,7 @@ function RootComponent() {
   )
 }
 
-function RootDocument({ children }: { children: React.ReactNode }) {
+function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
   return (
     <Html>
       <Head>

docs/framework/react/start/overview.md

@@ -89,9 +89,9 @@ TanStack works closely with our partners to provide the best possible developer
 - **Convex**
   <a href="https://convex.dev?utm_source=tanstack" alt="Convex Logo">
   <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tanstack/tanstack.com/main/app/images/convex-white.svg" style="height: 80px;">
-  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/tanstack/tanstack.com/main/app/images/convex-color.svg" style="height: 80px;">
-  <img alt="Convex logo" src="https://raw.githubusercontent.com/tanstack/tanstack.com/main/app/images/convex-color.svg" style="height: 80px;">
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tanstack/tanstack.com/main/app/images/convex-white.svg" style="height: 40px;">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/tanstack/tanstack.com/main/app/images/convex-color.svg" style="height: 40px;">
+  <img alt="Convex logo" src="https://raw.githubusercontent.com/tanstack/tanstack.com/main/app/images/convex-color.svg" style="height: 40px;">
   </picture>
   </a>
   A serverless database platform that integrates seamlessly with TanStack Start. Convex is designed to simplify the process of managing your application's data and provides a real-time, scalable, and transactional data backend that works well with TanStack Start applications. Convex also collaborates closely with the TanStack team to ensure that TanStack Start provides APIs that are up to date with the latest in database best practices.

e2e/react-router/basic-esbuild-file-based/package.json

@@ -20,9 +20,9 @@
     "zod": "^3.23.8"
   },
   "devDependencies": {
-    "@playwright/test": "^1.48.0",
+    "@playwright/test": "^1.48.2",
     "@types/react": "^18.2.47",
     "@types/react-dom": "^18.2.18",
-    "esbuild": "^0.23.1"
+    "esbuild": "^0.24.0"
   }
 }