@tanstack/router-core 1.169.0 → 1.169.2

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

@@ -21,6 +21,10 @@ sources:
 
 # Auth and Guards
 
+> **This skill covers the routing side of auth.** For the **server-side primitives** — session cookies (`HttpOnly`/`Secure`/`SameSite`), `useSession`-style helpers, OAuth `state` + PKCE, password-reset enumeration defense, CSRF, rate limiting — see [start-core/auth-server-primitives](../../../../start-client-core/skills/start-core/auth-server-primitives/SKILL.md). The two skills are designed to be used together.
+>
+> **CRITICAL**: A route guard (`beforeLoad`) does NOT protect a `createServerFn` declared on that route. Server functions are RPC endpoints reachable by direct POST regardless of which route renders them. See "Route guards do not protect server functions" below.
+
 ## Setup
 
 Protect routes with `beforeLoad` + `redirect()` in a pathless layout route (`_authenticated`):
@@ -371,6 +375,41 @@ export const Route = createFileRoute('/_authenticated')({
 
 ## Common Mistakes
 
+### CRITICAL: Route guards do not protect server functions
+
+A `beforeLoad` redirect protects the **route's UI**, not the **server functions** declared on it. `createServerFn` produces an RPC endpoint reachable by direct POST regardless of which route renders the calling UI. An attacker doesn't have to load `/_authenticated/orders` — they can curl the RPC endpoint directly.
+
+```tsx
+// WRONG — handler has no auth check; the route guard doesn't help
+import { createServerFn } from '@tanstack/react-start'
+import { createFileRoute, redirect } from '@tanstack/react-router'
+
+const getMyOrders = createServerFn({ method: 'GET' }).handler(async () => {
+  return db.orders.findMany() // ← anyone can hit the RPC
+})
+
+export const Route = createFileRoute('/_authenticated/orders')({
+  beforeLoad: ({ context }) => {
+    if (!context.auth.isAuthenticated) throw redirect({ to: '/login' })
+  },
+  loader: () => getMyOrders(),
+})
+```
+
+```tsx
+// CORRECT — auth enforced on the handler itself, via middleware
+import { createServerFn } from '@tanstack/react-start'
+import { authMiddleware } from '~/server/auth-middleware'
+
+const getMyOrders = createServerFn({ method: 'GET' })
+  .middleware([authMiddleware])
+  .handler(async ({ context }) => {
+    return db.orders.findMany({ where: { userId: context.session.userId } })
+  })
+```
+
+Rule of thumb: every `createServerFn` that touches user data needs `authMiddleware` (or an equivalent in-handler check). The route guard is for the page experience; the RPC guard is for the data. See [start-core/auth-server-primitives](../../../../start-client-core/skills/start-core/auth-server-primitives/SKILL.md) for the full session/middleware pattern.
+
 ### HIGH: Auth check in component instead of beforeLoad
 
 Component-level auth checks cause a **flash of protected content** before the redirect:
@@ -456,3 +495,5 @@ Place protected routes as children of the `_authenticated` layout route. Public
 ## Cross-References
 
 - See also: **router-core/data-loading/SKILL.md** — `beforeLoad` runs before `loader`; auth context flows into loader via route context
+- See also: **start-core/auth-server-primitives/SKILL.md** — server-side session cookies, OAuth state + PKCE, CSRF, password-reset hardening, rate limiting (the server half of authentication)
+- See also: **start-core/middleware/SKILL.md** — `authMiddleware` factory pattern for protecting individual `createServerFn` calls

package/skills/router-core/ssr/SKILL.md

@@ -391,22 +391,74 @@ component: () => {
 }
 ```
 
-### 3. CRITICAL: Generating Next.js or Remix SSR patterns
+### 3. CRITICAL: Generating Next.js, Remix, or React Router DOM patterns
 
-TanStack Router does NOT use `getServerSideProps`, `getStaticProps`, App Router `page.tsx`, or Remix-style server-only `loader` exports.
+TanStack Router does NOT use `getServerSideProps`, `getStaticProps`, App Router `page.tsx`, Remix-style server-only `loader` exports, or anything from `react-router-dom`.
+
+#### Wrong file structures
+
+```text
+WRONG (Next.js Pages Router):
+  src/pages/index.tsx
+  src/pages/_app.tsx
+  src/pages/posts/[id].tsx
+
+WRONG (Next.js App Router):
+  app/layout.tsx
+  app/page.tsx
+  app/posts/[id]/page.tsx
+
+WRONG (Next.js custom App):
+  _app/index.tsx
+  pages/_app.tsx, pages/_document.tsx
+
+CORRECT (TanStack Router file-based routing):
+  src/routes/__root.tsx
+  src/routes/index.tsx
+  src/routes/posts/$postId.tsx
+```
+
+#### Wrong imports
 
 ```tsx
-// WRONG — Next.js patterns
+// WRONG — react-router-dom is a different library
+import {
+  Link,
+  useNavigate,
+  BrowserRouter,
+  Route,
+  Routes,
+} from 'react-router-dom'
+
+// WRONG — Next.js Link/router
+import Link from 'next/link'
+import { useRouter } from 'next/router' // Pages Router
+import { useRouter } from 'next/navigation' // App Router
+
+// CORRECT — everything routing-related lives in @tanstack/react-router
+import {
+  Link,
+  useNavigate,
+  useRouter,
+  useLocation,
+  redirect,
+} from '@tanstack/react-router'
+```
+
+#### Wrong loader/data-fetching patterns
+
+```tsx
+// WRONG — Next.js Pages Router
 export async function getServerSideProps() {
   return { props: { data: await fetchData() } }
 }
 
-// WRONG — Remix patterns
+// WRONG — Remix
 export async function loader({ request }: LoaderFunctionArgs) {
   return json({ data: await fetchData() })
 }
 
-// CORRECT — TanStack Router pattern
+// CORRECT — TanStack Router
 export const Route = createFileRoute('/data')({
   loader: async () => {
     const data = await fetchData()
@@ -421,6 +473,8 @@ function DataPage() {
 }
 ```
 
+If you see `src/pages/`, `app/layout.tsx`, `react-router-dom`, or any of the above in agent output, the agent is generating for the wrong framework. The build will either fail or produce duplicate `/` routes that conflict at runtime.
+
 ## Tension: Client-First Loaders vs SSR
 
 TanStack Router loaders are client-first by design. When SSR is enabled, they run in both environments. This means:

package/skills/router-core/type-safety/SKILL.md

@@ -313,7 +313,9 @@ export function NavItem(props: NavItemProps): React.ReactNode {
 <NavItem label="Post" linkOptions={{ to: '/posts/$postId', params: { postId: '1' } }} />
 ```
 
-### `ValidateNavigateOptions` — Type-Safe Navigate in Utilities
+### `ValidateNavigateOptions` and `ValidateRedirectOptions`
+
+Same pattern as `ValidateLinkOptions` above, for `useNavigate` and `redirect`. Declare a generic public overload plus a non-generic implementation signature so the call site stays narrowed and the body works without casts:
 
 ```tsx
 import {
@@ -332,45 +334,15 @@ export function useDelayedNavigate<
 export function useDelayedNavigate(
   options: ValidateNavigateOptions,
   delayMs: number,
-): () => void {
+) {
   const navigate = useNavigate()
   return () => {
     setTimeout(() => navigate(options), delayMs)
   }
 }
-
-// Usage — type-safe
-const go = useDelayedNavigate(
-  { to: '/posts/$postId', params: { postId: '1' } },
-  500,
-)
 ```
 
-### `ValidateRedirectOptions` — Type-Safe Redirect in Utilities
-
-```tsx
-import {
-  redirect,
-  type RegisteredRouter,
-  type ValidateRedirectOptions,
-} from '@tanstack/react-router'
-
-export async function fetchOrRedirect<
-  TRouter extends RegisteredRouter = RegisteredRouter,
-  TOptions = unknown,
->(
-  url: string,
-  redirectOptions: ValidateRedirectOptions<TRouter, TOptions>,
-): Promise<unknown>
-export async function fetchOrRedirect(
-  url: string,
-  redirectOptions: ValidateRedirectOptions,
-): Promise<unknown> {
-  const response = await fetch(url)
-  if (!response.ok && response.status === 401) throw redirect(redirectOptions)
-  return response.json()
-}
-```
+`ValidateRedirectOptions` works identically — declare a generic overload accepting `ValidateRedirectOptions<TRouter, TOptions>` and an impl signature accepting `ValidateRedirectOptions`, then call `redirect(options)` in the body.
 
 ### Render Props for Maximum Performance
 
@@ -477,21 +449,44 @@ declare module '@tanstack/react-router' {
 }
 ```
 
-### 5. CRITICAL (cross-skill): Generating Next.js or Remix patterns
+### 5. CRITICAL (cross-skill): Wrong-framework imports and file structure
+
+Wrong-framework code looks plausible (it's React) but breaks the build or produces conflicting `/` routes at runtime.
 
 ```tsx
-// WRONG — these are NOT TanStack Router APIs
-export async function getServerSideProps() { ... }
-export async function loader({ request }) { ... } // Remix-style
-const [searchParams, setSearchParams] = useSearchParams() // React Router
+// WRONG — react-router-dom and next/* are different libraries
+import { Link, useNavigate, useSearchParams } from 'react-router-dom'
+import Link from 'next/link'
+import { useRouter, useParams } from 'next/navigation'
 
-// CORRECT — TanStack Router APIs
+// CORRECT — all routing exports come from @tanstack/react-router
+import {
+  Link,
+  Outlet,
+  useNavigate,
+  useRouter,
+  useLocation,
+  useParams,
+  redirect,
+} from '@tanstack/react-router'
+```
+
+```tsx
+// WRONG file structures + APIs:
+//   src/pages/*.tsx with getServerSideProps / getStaticProps  (Next.js Pages Router)
+//   app/layout.tsx + app/page.tsx                              (Next.js App Router)
+//   _app/index.tsx, pages/_app.tsx, pages/_document.tsx        (Next.js custom App)
+//   loader/action exports                                       (Remix)
+
+// CORRECT — TanStack file-based routing at src/routes/*.tsx
 export const Route = createFileRoute('/posts')({
-  loader: async () => { ... },           // TanStack loader
-  validateSearch: zodValidator(schema),   // TanStack search validation
+  loader: async () => { ... },
+  validateSearch: zodValidator(schema),
   component: PostsComponent,
 })
-const search = Route.useSearch()          // TanStack hook
+const search = Route.useSearch()
 ```
 
+If a build error mentions `react-router-dom`, `next/`, `pages/_app`, or duplicate `/` routes, fix the import — don't paper over with type assertions.
+
 See also: router-core (Register setup), router-core/navigation (from narrowing), router-core/code-splitting (getRouteApi).

package/src/load-matches.ts

@@ -713,7 +713,7 @@ const runLoader = async (
       const pendingPromise = match._nonReactive.minPendingPromise
       if (pendingPromise) await pendingPromise
 
-      // Last but not least, wait for the the components
+      // Last but not least, wait for the components
       // to be preloaded before we resolve the match
       if (route._componentsPromise) await route._componentsPromise
       inner.updateMatch(matchId, (prev) => ({

package/src/route.ts

@@ -173,11 +173,13 @@ export type ResolveParams<
 
 export type ParseParamsFn<in out TPath extends string, in out TParams> = (
   rawParams: Expand<ResolveParams<TPath>>,
-) =>
-  | (TParams extends ResolveParams<TPath, any>
-      ? TParams
-      : ResolveParams<TPath, any>)
-  | false
+) => TParams | false
+
+type ValidateParsedParams<TPath extends string, TParams> = [TParams] extends [
+  ResolveParams<TPath, any>,
+]
+  ? unknown
+  : never
 
 export type StringifyParamsFn<in out TPath extends string, in out TParams> = (
   params: TParams,
@@ -185,14 +187,15 @@ export type StringifyParamsFn<in out TPath extends string, in out TParams> = (
 
 export type ParamsOptions<in out TPath extends string, in out TParams> = {
   params?: {
-    parse?: ParseParamsFn<TPath, TParams>
+    parse?: ParseParamsFn<TPath, TParams> & ValidateParsedParams<TPath, TParams>
     stringify?: StringifyParamsFn<TPath, TParams>
   }
 
   /** 
   @deprecated Use params.parse instead
   */
-  parseParams?: ParseParamsFn<TPath, TParams>
+  parseParams?: ParseParamsFn<TPath, TParams> &
+    ValidateParsedParams<TPath, TParams>
 
   /** 
   @deprecated Use params.stringify instead

package/bin/intent.js

@@ -1,25 +0,0 @@
-#!/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
-}