refactor(router-core,start-server-core): improve JSDocs for redirect (#4848)

Co-authored-by: Christopher Menendez <[email protected]>

Author: Christopher96u

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

@@ -36,3 +36,12 @@ The `Redirect` object accepts/contains the following properties:
 - Type: `HeadersInit`
 - Optional
 - The HTTP headers to use when redirecting.
+
+### Navigation Properties
+
+Since `Redirect` extends `NavigateOptions`, it also supports navigation properties:
+
+- **`to`**: Use for internal application routes (e.g., `/dashboard`, `../profile`)
+- **`href`**: Use for external URLs (e.g., `https://example.com`, `https://authprovider.com`)
+
+> **Important**: For external URLs, always use the `href` property instead of `to`. The `to` property is designed for internal navigation within your application.

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

@@ -23,14 +23,22 @@ The `redirect` function accepts a single argument, the `options` to determine th
 import { redirect } from '@tanstack/react-router'
 
 const route = createRoute({
-  // throwing a redirect object
+  // throwing an internal redirect object using 'to' property
   loader: () => {
     if (!user) {
       throw redirect({
         to: '/login',
       })
     }
   },
+  // throwing an external redirect object using 'href' property
+  loader: () => {
+    if (needsExternalAuth) {
+      throw redirect({
+        href: 'https://authprovider.com/login',
+      })
+    }
+  },
   // or forcing `redirect` to throw itself
   loader: () => {
     if (!user) {

packages/router-core/src/link.ts

@@ -393,6 +393,12 @@ export interface RequiredToOptions<
   in out TFrom extends string,
   in out TTo extends string | undefined,
 > {
+  /**
+   * The internal route path to navigate to. This should be a relative or absolute path within your application.
+   * For external URLs, use the `href` property instead.
+   * @example "/dashboard" or "../profile"
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/NavigateOptionsType#href)
+   */
   to: ToPathOption<TRouter, TFrom, TTo> & {}
 }
 
@@ -401,6 +407,12 @@ export interface OptionalToOptions<
   in out TFrom extends string,
   in out TTo extends string | undefined,
 > {
+  /**
+   * The internal route path to navigate to. This should be a relative or absolute path within your application.
+   * For external URLs, use the `href` property instead.
+   * @example "/dashboard" or "../profile"
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/NavigateOptionsType#href)
+   */
   to?: ToPathOption<TRouter, TFrom, TTo> & {}
 }
 

packages/start-server-core/src/createStartHandler.ts

@@ -279,7 +279,7 @@ export function createStartHandler<TRouter extends AnyRouter>({
           !response.options.to.startsWith('/')
         ) {
           throw new Error(
-            `Server side redirects must use absolute paths via the 'href' or 'to' options. Received: ${JSON.stringify(response.options)}`,
+            `Server side redirects must use absolute paths via the 'href' or 'to' options. The redirect() method's "to" property accepts an internal path only. Use the "href" property to provide an external URL. Received: ${JSON.stringify(response.options)}`,
           )
         }