@tanstack/react-router 1.147.3 → 1.150.0

package/dist/llms/rules/api.js

@@ -730,6 +730,38 @@ The \`RouteApi\` has the following properties and methods:
 
 - A type-safe version of [\`useNavigate\`](./useNavigateHook.md) that is pre-bound to the route ID that the \`RouteApi\` instance was created with.
 
+### \`redirect\` method
+
+\`\`\`tsx
+  redirect(opts?: RedirectOptions): Redirect
+\`\`\`
+
+- A type-safe version of the [\`redirect\`](./redirectFunction.md) function that is pre-bound to the route ID that the \`RouteApi\` instance was created with.
+- The \`from\` parameter is automatically set to the route ID, enabling type-safe relative redirects.
+- Options
+  - All options from [\`redirect\`](./redirectFunction.md) except \`from\`, which is automatically provided.
+- Returns
+  - A \`Redirect\` object that can be thrown from \`beforeLoad\` or \`loader\` callbacks.
+
+#### Example
+
+\`\`\`tsx
+import { getRouteApi } from '@tanstack/react-router'
+
+const routeApi = getRouteApi('/dashboard/settings')
+
+export const Route = createFileRoute('/dashboard/settings')({
+  beforeLoad: ({ context }) => {
+    if (!context.user) {
+      // Type-safe redirect - 'from' is automatically '/dashboard/settings'
+      throw routeApi.redirect({
+        to: '../login', // Relative path to sibling route
+      })
+    }
+  },
+})
+\`\`\`
+
 # Route class
 
 > [!CAUTION]
@@ -1217,6 +1249,30 @@ An instance of the \`Route\` has the following properties and methods:
 - Type: \`(lazyImporter: () => Promise<Partial<UpdatableRouteOptions>>) => this\`
 - Updates the route instance with a new lazy importer which will be resolved lazily when loading the route. This can be useful for code splitting.
 
+### \`.redirect\` method
+
+- Type: \`(opts?: RedirectOptions) => Redirect\`
+- A type-safe version of the [\`redirect\`](./redirectFunction.md) function that is pre-bound to the route's path.
+- The \`from\` parameter is automatically set to the route's \`fullPath\`, enabling type-safe relative redirects.
+- See [\`RouteApi.redirect\`](./RouteApiType.md#redirect-method) for more details.
+
+#### Example
+
+\`\`\`tsx
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/dashboard/settings')({
+  beforeLoad: ({ context }) => {
+    if (!context.user) {
+      // Type-safe redirect - 'from' is automatically '/dashboard/settings'
+      throw Route.redirect({
+        to: '../login', // Relative path to sibling route
+      })
+    }
+  },
+})
+\`\`\`
+
 ### ...\`RouteApi\` methods
 
 - All of the methods from [\`RouteApi\`](./RouteApiType.md) are available.
@@ -3059,6 +3115,8 @@ The \`redirect\` function accepts a single argument, the \`options\` to determin
 
 ## Examples
 
+### Using the standalone \`redirect\` function
+
 \`\`\`tsx
 import { redirect } from '@tanstack/react-router'
 
@@ -3092,6 +3150,62 @@ const route = createRoute({
 })
 \`\`\`
 
+### Using Route.redirect (File-Based Routes)
+
+When using file-based routing with \`createFileRoute\`, you can use the \`Route.redirect\` method directly. This method automatically sets the \`from\` parameter based on the route's path, enabling type-safe relative redirects without manually specifying the origin route:
+
+\`\`\`tsx
+// In routes/dashboard/settings.tsx
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/dashboard/settings')({
+  beforeLoad: ({ context }) => {
+    if (!context.user) {
+      // Relative redirect - automatically knows we're redirecting from '/dashboard/settings'
+      throw Route.redirect({
+        to: '../login', // Redirects to '/dashboard/login'
+      })
+    }
+  },
+  loader: () => {
+    // Also works in loader
+    if (needsMigration) {
+      throw Route.redirect({
+        to: './migrate', // Redirects to '/dashboard/settings/migrate'
+      })
+    }
+  },
+})
+\`\`\`
+
+### Using getRouteApi().redirect
+
+For accessing the redirect method outside of the route definition file, you can use \`getRouteApi\`:
+
+\`\`\`tsx
+import { getRouteApi } from '@tanstack/react-router'
+
+const routeApi = getRouteApi('/dashboard/settings')
+
+// In a beforeLoad or loader callback
+function checkAuth() {
+  if (!user) {
+    // Type-safe redirect with automatic 'from' parameter
+    throw routeApi.redirect({
+      to: '../login',
+    })
+  }
+}
+\`\`\`
+
+### Benefits of Route-Bound Redirect
+
+Using \`Route.redirect\` or \`getRouteApi().redirect\` instead of the standalone \`redirect\` function offers several advantages:
+
+1. **No need to specify \`from\`**: The route path is automatically used as the origin
+2. **Type-safe relative paths**: TypeScript validates that relative paths like \`../sibling\` or \`./child\` resolve to valid routes
+3. **Refactoring-friendly**: If the route path changes, the redirect origin updates automatically
+
 # Search middleware to retain search params
 
 \`retainSearchParams\` is a search middleware that allows to keep search params.