docs: some best practices

tannerlinsley · tannerlinsley · commit e6862d1af99b · 2026-01-10T23:19:36.000-07:00
diff --git a/docs/router/framework/react/guide/authenticated-routes.md b/docs/router/framework/react/guide/authenticated-routes.md
@@ -51,6 +51,41 @@ export const Route = createFileRoute('/_authenticated')({
 > [!TIP]
 > The `redirect()` function takes all of the same options as the `navigate` function, so you can pass options like `replace: true` if you want to replace the current history entry instead of adding a new one.
 
+### Handling Auth Check Failures
+
+If your authentication check can throw errors (network failures, token validation, etc.), wrap it in try/catch:
+
+```tsx
+import { createFileRoute, redirect, isRedirect } from '@tanstack/react-router'
+
+// src/routes/_authenticated.tsx
+export const Route = createFileRoute('/_authenticated')({
+  beforeLoad: async ({ location }) => {
+    try {
+      const user = await verifySession() // might throw on network error
+      if (!user) {
+        throw redirect({
+          to: '/login',
+          search: { redirect: location.href },
+        })
+      }
+      return { user }
+    } catch (error) {
+      // Re-throw redirects (they're intentional, not errors)
+      if (isRedirect(error)) throw error
+
+      // Auth check failed (network error, etc.) - redirect to login
+      throw redirect({
+        to: '/login',
+        search: { redirect: location.href },
+      })
+    }
+  },
+})
+```
+
+The [`isRedirect()`](../api/router/isRedirectFunction.md) helper distinguishes between actual errors and intentional redirects.
+
 Once you have authenticated a user, it's also common practice to redirect them back to the page they were trying to access. To do this, you can utilize the `redirect` search param that we added in our original redirect. Since we'll be replacing the entire URL with what it was, `router.history.push` is better suited for this than `router.navigate`:
 
 ```tsx
diff --git a/docs/router/framework/react/guide/data-loading.md b/docs/router/framework/react/guide/data-loading.md
@@ -160,6 +160,28 @@ export const Route = createFileRoute('/posts')({
 })
 ```
 
+> [!WARNING]
+> **Only include dependencies you actually use in the loader.**
+>
+> A common mistake is returning the entire `search` object:
+>
+> ```tsx
+> // ❌ Don't do this - causes unnecessary cache invalidation
+> loaderDeps: ({ search }) => search,
+> loader: ({ deps }) => fetchPosts({ page: deps.page }), // only uses page!
+> ```
+>
+> This causes the route to reload whenever ANY search param changes, even params not used in the loader (like `viewMode` or `sortDirection`). Instead, extract only what you need:
+>
+> ```tsx
+> // ✅ Do this - only reload when used params change
+> loaderDeps: ({ search }) => ({
+>   page: search.page,
+>   limit: search.limit,
+> }),
+> loader: ({ deps }) => fetchPosts(deps),
+> ```
+
 ### Using `staleTime` to control how long data is considered fresh
 
 By default, `staleTime` for navigations is set to `0`ms (and 30 seconds for preloads) which means that the route's data will always be considered stale and will always be reloaded in the background when the route is matched and navigated to.
diff --git a/docs/router/framework/react/guide/document-head-management.md b/docs/router/framework/react/guide/document-head-management.md
@@ -156,3 +156,66 @@ export const Route = createRootRoute({
   ),
 })
 ```
+
+## Inline Scripts with ScriptOnce
+
+For scripts that must run before React hydrates (like theme detection), use `ScriptOnce`. This is particularly useful for avoiding flash of unstyled content (FOUC) or theme flicker.
+
+```tsx
+import { ScriptOnce } from '@tanstack/react-router'
+
+const themeScript = `(function() {
+  try {
+    const theme = localStorage.getItem('theme') || 'auto';
+    const resolved = theme === 'auto'
+      ? (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
+      : theme;
+    document.documentElement.classList.add(resolved);
+  } catch (e) {}
+})();`
+
+function ThemeProvider({ children }) {
+  return (
+    <>
+      <ScriptOnce children={themeScript} />
+      {children}
+    </>
+  )
+}
+```
+
+### How ScriptOnce Works
+
+1. During SSR, renders a `<script>` tag with the provided code
+2. The script executes immediately when the browser parses the HTML (before React hydrates)
+3. After execution, the script removes itself from the DOM
+4. On client-side navigation, nothing is rendered (prevents duplicate execution)
+
+### Preventing Hydration Warnings
+
+If your script modifies the DOM before hydration (like adding a class to `<html>`), use `suppressHydrationWarning` to prevent React warnings:
+
+```tsx
+export const Route = createRootRoute({
+  component: () => (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <ThemeProvider>
+          <Outlet />
+        </ThemeProvider>
+        <Scripts />
+      </body>
+    </html>
+  ),
+})
+```
+
+### Common Use Cases
+
+- **Theme/dark mode detection** - Apply theme class before hydration to prevent flash
+- **Feature detection** - Check browser capabilities before rendering
+- **Analytics initialization** - Initialize tracking before user interaction
+- **Critical path setup** - Any JavaScript that must run before hydration
diff --git a/docs/router/framework/react/guide/static-route-data.md b/docs/router/framework/react/guide/static-route-data.md
@@ -79,3 +79,73 @@ declare module '@tanstack/react-router' {
 ```
 
 As long as there are any required properties on the `StaticDataRouteOption`, you'll be required to pass in an object.
+
+## Common Patterns
+
+### Controlling Layout Visibility
+
+Use staticData to control which routes show or hide layout elements:
+
+```tsx
+// routes/admin/route.tsx
+export const Route = createFileRoute('/admin')({
+  staticData: { showNavbar: false },
+  component: AdminLayout,
+})
+```
+
+```tsx
+// routes/__root.tsx
+function RootComponent() {
+  const showNavbar = useMatches({
+    select: (matches) =>
+      !matches.some((m) => m.staticData?.showNavbar === false),
+  })
+
+  return showNavbar ? (
+    <Navbar>
+      <Outlet />
+    </Navbar>
+  ) : (
+    <Outlet />
+  )
+}
+```
+
+### Route Titles for Breadcrumbs
+
+```tsx
+// routes/posts/$postId.tsx
+export const Route = createFileRoute('/posts/$postId')({
+  staticData: {
+    getTitle: () => 'Post Details',
+  },
+})
+```
+
+```tsx
+// In a Breadcrumb component
+function Breadcrumbs() {
+  const matches = useMatches()
+
+  return (
+    <nav>
+      {matches
+        .filter((m) => m.staticData?.getTitle)
+        .map((m) => (
+          <span key={m.id}>{m.staticData.getTitle()}</span>
+        ))}
+    </nav>
+  )
+}
+```
+
+### When to Use staticData vs Context
+
+| staticData                             | context                         |
+| -------------------------------------- | ------------------------------- |
+| Synchronous, defined at route creation | Can be async (via `beforeLoad`) |
+| Available before loading starts        | Can depend on params/search     |
+| Same for all instances of a route      | Passed down to child routes     |
+
+Use staticData for static route metadata. Use context for dynamic data or auth state that varies per request.
diff --git a/docs/start/framework/react/guide/server-functions.md b/docs/start/framework/react/guide/server-functions.md
@@ -66,6 +66,70 @@ function PostList() {
 }
 ```
 
+## File Organization
+
+For larger applications, consider organizing server-side code into separate files. Here's one approach:
+
+```
+src/utils/
+├── users.functions.ts   # Server function wrappers (createServerFn)
+├── users.server.ts      # Server-only helpers (DB queries, internal logic)
+└── schemas.ts           # Shared validation schemas (client-safe)
+```
+
+- **`.functions.ts`** - Export `createServerFn` wrappers, safe to import anywhere
+- **`.server.ts`** - Server-only code, only imported inside server function handlers
+- **`.ts`** (no suffix) - Client-safe code (types, schemas, constants)
+
+### Example
+
+```tsx
+// users.server.ts - Server-only helpers
+import { db } from '~/db'
+
+export async function findUserById(id: string) {
+  return db.query.users.findFirst({ where: eq(users.id, id) })
+}
+```
+
+```tsx
+// users.functions.ts - Server functions
+import { createServerFn } from '@tanstack/react-start'
+import { findUserById } from './users.server'
+
+export const getUser = createServerFn({ method: 'GET' })
+  .inputValidator((data: { id: string }) => data)
+  .handler(async ({ data }) => {
+    return findUserById(data.id)
+  })
+```
+
+### Static Imports Are Safe
+
+Server functions can be statically imported in any file, including client components:
+
+```tsx
+// ✅ Safe - build process handles environment shaking
+import { getUser } from '~/utils/users.functions'
+
+function UserProfile({ id }) {
+  const { data } = useQuery({
+    queryKey: ['user', id],
+    queryFn: () => getUser({ data: { id } }),
+  })
+}
+```
+
+The build process replaces server function implementations with RPC stubs in client bundles. The actual server code never reaches the browser.
+
+> [!WARNING]
+> Avoid dynamic imports for server functions:
+>
+> ```tsx
+> // ❌ Can cause bundler issues
+> const { getUser } = await import('~/utils/users.functions')
+> ```
+
 ## Parameters & Validation
 
 Server functions accept a single `data` parameter. Since they cross the network boundary, validation ensures type safety and runtime correctness.
@@ -197,12 +261,46 @@ For more advanced server function patterns and features, see these dedicated gui
 
 ### Server Context & Request Handling
 
-Access request headers, cookies, and response customization:
+Access request headers, cookies, and customize responses:
+
+```tsx
+import { createServerFn } from '@tanstack/react-start'
+import {
+  getRequest,
+  getRequestHeader,
+  setResponseHeaders,
+  setResponseStatus,
+} from '@tanstack/react-start/server'
+
+export const getCachedData = createServerFn({ method: 'GET' }).handler(
+  async () => {
+    // Access the incoming request
+    const request = getRequest()
+    const authHeader = getRequestHeader('Authorization')
+
+    // Set response headers (e.g., for caching)
+    setResponseHeaders(
+      new Headers({
+        'Cache-Control': 'public, max-age=300',
+        'CDN-Cache-Control': 'max-age=3600, stale-while-revalidate=600',
+      }),
+    )
+
+    // Optionally set status code
+    setResponseStatus(200)
+
+    return fetchData()
+  },
+)
+```
+
+Available utilities:
 
-- `getRequest()` - Access the full request object
-- `getRequestHeader()` - Read specific headers
-- `setResponseHeader()` - Set custom response headers
-- `setResponseStatus()` - Custom status codes
+- `getRequest()` - Access the full Request object
+- `getRequestHeader(name)` - Read a specific request header
+- `setResponseHeader(name, value)` - Set a single response header
+- `setResponseHeaders(headers)` - Set multiple response headers via Headers object
+- `setResponseStatus(code)` - Set the HTTP status code
 
 ### Streaming
 
