@tanstack/router-core 1.167.3 → 1.167.5

package/bin/intent.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Auto-generated by @tanstack/intent setup
+// Exposes the intent end-user CLI for consumers of this library.
+// Commit this file, then add to your package.json:
+//   "bin": { "intent": "./bin/intent.js" }
+try {
+  await import('@tanstack/intent/intent-library')
+} catch (e) {
+  const isModuleNotFound =
+    e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND'
+  const missingIntentLibrary =
+    typeof e?.message === 'string' && e.message.includes('@tanstack/intent')
+
+  if (isModuleNotFound && missingIntentLibrary) {
+    console.error('@tanstack/intent is not installed.')
+    console.error('')
+    console.error('Install it as a dev dependency:')
+    console.error('  npm add -D @tanstack/intent')
+    console.error('')
+    console.error('Or run directly:')
+    console.error('  npx @tanstack/intent@latest list')
+    process.exit(1)
+  }
+  throw e
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/router-core",
-  "version": "1.167.3",
+  "version": "1.167.5",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -138,7 +138,10 @@
   "sideEffects": false,
   "files": [
     "dist",
-    "src"
+    "src",
+    "skills",
+    "bin",
+    "!skills/_artifacts"
   ],
   "engines": {
     "node": ">=20.19"
@@ -153,9 +156,13 @@
     "@tanstack/history": "1.161.6"
   },
   "devDependencies": {
-    "esbuild": "^0.25.0",
+    "@tanstack/intent": "^0.0.14",
+    "esbuild": "^0.27.4",
     "vite": "*"
   },
+  "bin": {
+    "intent": "./bin/intent.js"
+  },
   "scripts": {
     "clean": "rimraf ./dist && rimraf ./coverage",
     "test:eslint": "eslint ./src",

package/skills/router-core/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: router-core
+description: >-
+  Framework-agnostic core concepts for TanStack Router: route trees,
+  createRouter, createRoute, createRootRoute, createRootRouteWithContext,
+  addChildren, Register type declaration, route matching, route sorting,
+  file naming conventions. Entry point for all router skills.
+type: core
+library: tanstack-router
+library_version: '1.166.2'
+---
+
+# TanStack Router Core
+
+TanStack Router is a type-safe router for React and Solid with built-in SWR caching, JSON-first search params, file-based route generation, and end-to-end type inference. The core is framework-agnostic; React and Solid bindings layer on top.
+
+> **CRITICAL**: TanStack Router types are FULLY INFERRED. Never cast, never annotate inferred values. This is the #1 AI agent mistake.
+
+> **CRITICAL**: TanStack Router is CLIENT-FIRST. Loaders run on the client by default, NOT server-only like Remix/Next.js. Do not confuse TanStack Router APIs with Next.js or React Router.
+
+## Sub-Skills
+
+| Task                                               | Sub-Skill                                                                    |
+| -------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Validate, read, write, transform search params     | [router-core/search-params/SKILL.md](./search-params/SKILL.md)               |
+| Dynamic segments, splats, optional params          | [router-core/path-params/SKILL.md](./path-params/SKILL.md)                   |
+| Link, useNavigate, preloading, blocking            | [router-core/navigation/SKILL.md](./navigation/SKILL.md)                     |
+| Route loaders, SWR caching, context, deferred data | [router-core/data-loading/SKILL.md](./data-loading/SKILL.md)                 |
+| Auth guards, RBAC, beforeLoad redirects            | [router-core/auth-and-guards/SKILL.md](./auth-and-guards/SKILL.md)           |
+| Automatic and manual code splitting                | [router-core/code-splitting/SKILL.md](./code-splitting/SKILL.md)             |
+| 404 handling, error boundaries, notFound()         | [router-core/not-found-and-errors/SKILL.md](./not-found-and-errors/SKILL.md) |
+| Inference, Register, from narrowing, TS perf       | [router-core/type-safety/SKILL.md](./type-safety/SKILL.md)                   |
+| Streaming/non-streaming SSR, hydration, head mgmt  | [router-core/ssr/SKILL.md](./ssr/SKILL.md)                                   |
+
+## Quick Decision Tree
+
+```
+Need to add/read/write URL query parameters?
+  → router-core/search-params
+
+Need dynamic URL segments like /posts/$postId?
+  → router-core/path-params
+
+Need to create links or navigate programmatically?
+  → router-core/navigation
+
+Need to fetch data for a route?
+  Is it client-side only or client+server?
+    → router-core/data-loading
+  Using TanStack Query as external cache?
+    → compositions/router-query (separate skill)
+
+Need to protect routes behind auth?
+  → router-core/auth-and-guards
+
+Need to reduce bundle size per route?
+  → router-core/code-splitting
+
+Need custom 404 or error handling?
+  → router-core/not-found-and-errors
+
+Having TypeScript issues or performance problems?
+  → router-core/type-safety
+
+Need server-side rendering?
+  → router-core/ssr
+```
+
+## Minimal Working Example
+
+```tsx
+// src/routes/__root.tsx
+import { createRootRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createRootRoute({
+  component: () => <Outlet />,
+})
+```
+
+```tsx
+// src/routes/index.tsx
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/')({
+  component: () => <h1>Home</h1>,
+})
+```
+
+```tsx
+// src/router.tsx
+import { createRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+
+const router = createRouter({ routeTree })
+
+// REQUIRED for type safety — without this, Link/useNavigate have no autocomplete
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router
+  }
+}
+
+export default router
+```
+
+```tsx
+// src/main.tsx
+import { RouterProvider } from '@tanstack/react-router'
+import router from './router'
+
+function App() {
+  return <RouterProvider router={router} />
+}
+```
+
+## Common Mistakes
+
+### HIGH: createFileRoute path string must match the file path
+
+The Vite plugin manages the path string in `createFileRoute`. Do not change it manually — it must match the file's location under `src/routes/`:
+
+```tsx
+// File: src/routes/posts/$postId.tsx
+export const Route = createFileRoute('/posts/$postId')({
+  // ✅ matches file path
+  component: PostPage,
+})
+
+export const Route = createFileRoute('/post/$postId')({
+  // ❌ silent mismatch
+  component: PostPage,
+})
+```
+
+The plugin auto-generates this string. If you rename a route file, the plugin updates it. Never edit the path string by hand.
+
+## Version Note
+
+This skill targets `@tanstack/router-core` v1.166.2 and `@tanstack/react-router` v1.166.2. APIs are stable. Splat routes use `$` (not `*`); the `*` compat alias will be removed in v2.

package/skills/router-core/auth-and-guards/SKILL.md

@@ -0,0 +1,458 @@
+---
+name: router-core/auth-and-guards
+description: >-
+  Route protection with beforeLoad, redirect()/throw redirect(),
+  isRedirect helper, authenticated layout routes (_authenticated),
+  non-redirect auth (inline login), RBAC with roles and permissions,
+  auth provider integration (Auth0, Clerk, Supabase), router context
+  for auth state.
+type: sub-skill
+library: tanstack-router
+library_version: '1.166.2'
+requires:
+  - router-core
+  - router-core/data-loading
+sources:
+  - TanStack/router:docs/router/guide/authenticated-routes.md
+  - TanStack/router:docs/router/how-to/setup-authentication.md
+  - TanStack/router:docs/router/how-to/setup-auth-providers.md
+  - TanStack/router:docs/router/how-to/setup-rbac.md
+---
+
+# Auth and Guards
+
+## Setup
+
+Protect routes with `beforeLoad` + `redirect()` in a pathless layout route (`_authenticated`):
+
+```tsx
+// src/routes/_authenticated.tsx
+import { createFileRoute, redirect } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_authenticated')({
+  beforeLoad: ({ context, location }) => {
+    if (!context.auth.isAuthenticated) {
+      throw redirect({
+        to: '/login',
+        search: {
+          redirect: location.href,
+        },
+      })
+    }
+  },
+  // component defaults to Outlet — no need to declare it
+})
+```
+
+Any route file placed under `src/routes/_authenticated/` is automatically protected:
+
+```tsx
+// src/routes/_authenticated/dashboard.tsx
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_authenticated/dashboard')({
+  component: DashboardComponent,
+})
+
+function DashboardComponent() {
+  const { auth } = Route.useRouteContext()
+  return <div>Welcome, {auth.user?.username}</div>
+}
+```
+
+## Core Patterns
+
+### Router Context for Auth State
+
+Auth state flows into the router via `createRootRouteWithContext` and `RouterProvider`'s `context` prop:
+
+```tsx
+// src/routes/__root.tsx
+import { createRootRouteWithContext, Outlet } from '@tanstack/react-router'
+
+interface AuthState {
+  isAuthenticated: boolean
+  user: { id: string; username: string; email: string } | null
+  login: (username: string, password: string) => Promise<void>
+  logout: () => void
+}
+
+interface MyRouterContext {
+  auth: AuthState
+}
+
+export const Route = createRootRouteWithContext<MyRouterContext>()({
+  component: () => <Outlet />,
+})
+```
+
+```tsx
+// src/router.tsx
+import { createRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+
+export const router = createRouter({
+  routeTree,
+  context: {
+    auth: undefined!, // placeholder — filled by RouterProvider context prop
+  },
+})
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router
+  }
+}
+```
+
+```tsx
+// src/App.tsx
+import { RouterProvider } from '@tanstack/react-router'
+import { AuthProvider, useAuth } from './auth'
+import { router } from './router'
+
+function InnerApp() {
+  const auth = useAuth()
+  // context prop injects live auth state WITHOUT recreating the router
+  return <RouterProvider router={router} context={{ auth }} />
+}
+
+function App() {
+  return (
+    <AuthProvider>
+      <InnerApp />
+    </AuthProvider>
+  )
+}
+```
+
+The router is created once with a placeholder. `RouterProvider`'s `context` prop injects the live auth state on each render — this avoids recreating the router on auth changes (which would reset caches and rebuild the route tree).
+
+### Redirect-Based Auth with Redirect-Back
+
+Save the current location in search params so you can redirect back after login:
+
+```tsx
+// src/routes/_authenticated.tsx
+import { createFileRoute, redirect } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_authenticated')({
+  beforeLoad: ({ context, location }) => {
+    if (!context.auth.isAuthenticated) {
+      throw redirect({
+        to: '/login',
+        search: { redirect: location.href },
+      })
+    }
+  },
+})
+```
+
+```tsx
+// src/routes/login.tsx
+import { createFileRoute, redirect } from '@tanstack/react-router'
+import { useState, type FormEvent } from 'react'
+
+// Validate redirect target to prevent open redirect attacks
+function sanitizeRedirect(url: unknown): string {
+  if (typeof url !== 'string' || !url.startsWith('/') || url.startsWith('//')) {
+    return '/'
+  }
+  return url
+}
+
+export const Route = createFileRoute('/login')({
+  validateSearch: (search) => ({
+    redirect: sanitizeRedirect(search.redirect),
+  }),
+  beforeLoad: ({ context, search }) => {
+    if (context.auth.isAuthenticated) {
+      throw redirect({ to: search.redirect })
+    }
+  },
+  component: LoginComponent,
+})
+
+function LoginComponent() {
+  const { auth } = Route.useRouteContext()
+  const search = Route.useSearch()
+  const navigate = Route.useNavigate()
+  const [username, setUsername] = useState('')
+  const [password, setPassword] = useState('')
+  const [error, setError] = useState('')
+
+  const handleSubmit = async (e: FormEvent) => {
+    e.preventDefault()
+    try {
+      await auth.login(username, password)
+      navigate({ to: search.redirect })
+    } catch {
+      setError('Invalid credentials')
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {error && <div>{error}</div>}
+      <input value={username} onChange={(e) => setUsername(e.target.value)} />
+      <input
+        type="password"
+        value={password}
+        onChange={(e) => setPassword(e.target.value)}
+      />
+      <button type="submit">Sign In</button>
+    </form>
+  )
+}
+```
+
+### Non-Redirect Auth (Inline Login)
+
+Instead of redirecting, show a login form in place of the `Outlet`:
+
+```tsx
+// src/routes/_authenticated.tsx
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_authenticated')({
+  component: AuthenticatedLayout,
+})
+
+function AuthenticatedLayout() {
+  const { auth } = Route.useRouteContext()
+
+  if (!auth.isAuthenticated) {
+    return <LoginForm />
+  }
+
+  return <Outlet />
+}
+```
+
+This keeps the URL unchanged — the user stays on the same page and sees a login form instead of protected content. After authentication, `<Outlet />` renders and child routes appear.
+
+### RBAC with Roles and Permissions
+
+Extend auth state with role/permission helpers, then check in `beforeLoad`:
+
+```tsx
+// src/auth.tsx
+interface User {
+  id: string
+  username: string
+  email: string
+  roles: string[]
+  permissions: string[]
+}
+
+interface AuthState {
+  isAuthenticated: boolean
+  user: User | null
+  hasRole: (role: string) => boolean
+  hasAnyRole: (roles: string[]) => boolean
+  hasPermission: (permission: string) => boolean
+  hasAnyPermission: (permissions: string[]) => boolean
+  login: (username: string, password: string) => Promise<void>
+  logout: () => void
+}
+```
+
+Admin-only layout route:
+
+```tsx
+// src/routes/_authenticated/_admin.tsx
+import { createFileRoute, redirect } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_authenticated/_admin')({
+  beforeLoad: ({ context, location }) => {
+    if (!context.auth.hasRole('admin')) {
+      throw redirect({
+        to: '/unauthorized',
+        search: { redirect: location.href },
+      })
+    }
+  },
+})
+```
+
+Multi-role access:
+
+```tsx
+// src/routes/_authenticated/_moderator.tsx
+import { createFileRoute, redirect } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_authenticated/_moderator')({
+  beforeLoad: ({ context, location }) => {
+    if (!context.auth.hasAnyRole(['admin', 'moderator'])) {
+      throw redirect({
+        to: '/unauthorized',
+        search: { redirect: location.href },
+      })
+    }
+  },
+})
+```
+
+Permission-based:
+
+```tsx
+// src/routes/_authenticated/_users.tsx
+import { createFileRoute, redirect } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_authenticated/_users')({
+  beforeLoad: ({ context, location }) => {
+    if (!context.auth.hasAnyPermission(['users:read', 'users:write'])) {
+      throw redirect({
+        to: '/unauthorized',
+        search: { redirect: location.href },
+      })
+    }
+  },
+})
+```
+
+Page-level permission check (nested under an already-role-protected layout):
+
+```tsx
+// src/routes/_authenticated/_users/manage.tsx
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_authenticated/_users/manage')({
+  beforeLoad: ({ context }) => {
+    if (!context.auth.hasPermission('users:write')) {
+      throw new Error('Write permission required')
+    }
+  },
+  component: UserManagement,
+})
+
+function UserManagement() {
+  const { auth } = Route.useRouteContext()
+  const canDelete = auth.hasPermission('users:delete')
+
+  return (
+    <div>
+      <h1>User Management</h1>
+      {canDelete && <button>Delete User</button>}
+    </div>
+  )
+}
+```
+
+### Handling Auth Check Failures (isRedirect)
+
+When `beforeLoad` has a try/catch, redirects (which work by throwing) can get swallowed. Use `isRedirect` to re-throw:
+
+```tsx
+import { createFileRoute, redirect, isRedirect } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_authenticated')({
+  beforeLoad: async ({ context, location }) => {
+    try {
+      const user = await verifySession(context.auth)
+      if (!user) {
+        throw redirect({
+          to: '/login',
+          search: { redirect: location.href },
+        })
+      }
+      return { user }
+    } catch (error) {
+      if (isRedirect(error)) throw error // re-throw redirect, don't swallow it
+      // Actual error — redirect to login
+      throw redirect({
+        to: '/login',
+        search: { redirect: location.href },
+      })
+    }
+  },
+})
+```
+
+## Common Mistakes
+
+### HIGH: Auth check in component instead of beforeLoad
+
+Component-level auth checks cause a **flash of protected content** before the redirect:
+
+```tsx
+// WRONG — protected content renders briefly before redirect
+export const Route = createFileRoute('/_authenticated/dashboard')({
+  component: () => {
+    const auth = useAuth()
+    if (!auth.isAuthenticated) return <Navigate to="/login" />
+    return <Dashboard />
+  },
+})
+
+// CORRECT — beforeLoad runs before any rendering
+export const Route = createFileRoute('/_authenticated/dashboard')({
+  beforeLoad: ({ context }) => {
+    if (!context.auth.isAuthenticated) {
+      throw redirect({ to: '/login' })
+    }
+  },
+  component: Dashboard,
+})
+```
+
+`beforeLoad` runs before any component rendering and before the loader. It completely prevents the flash.
+
+### HIGH: Not re-throwing redirects in try/catch
+
+`redirect()` works by throwing. If `beforeLoad` has a try/catch, the redirect gets swallowed:
+
+```tsx
+// WRONG — redirect is caught and swallowed
+beforeLoad: async ({ context }) => {
+  try {
+    await validateSession(context.auth)
+  } catch (e) {
+    console.error(e) // swallows the redirect!
+  }
+}
+
+// CORRECT — use isRedirect to distinguish intentional redirects from errors
+import { isRedirect } from '@tanstack/react-router'
+
+beforeLoad: async ({ context }) => {
+  try {
+    await validateSession(context.auth)
+  } catch (e) {
+    if (isRedirect(e)) throw e
+    console.error(e)
+  }
+}
+```
+
+### MEDIUM: Conditionally rendering root route component
+
+The root route always renders regardless of auth state. You cannot conditionally render its component:
+
+```tsx
+// WRONG — root route always renders, this doesn't protect anything
+export const Route = createRootRoute({
+  component: () => {
+    if (!isAuthenticated()) return <Login />
+    return <Outlet />
+  },
+})
+
+// CORRECT — use a pathless layout route for auth boundaries
+// src/routes/_authenticated.tsx
+export const Route = createFileRoute('/_authenticated')({
+  beforeLoad: ({ context }) => {
+    if (!context.auth.isAuthenticated) {
+      throw redirect({ to: '/login' })
+    }
+  },
+})
+```
+
+Place protected routes as children of the `_authenticated` layout route. Public routes (login, home, etc.) live outside it.
+
+---
+
+## Cross-References
+
+- See also: **router-core/data-loading/SKILL.md** — `beforeLoad` runs before `loader`; auth context flows into loader via route context