@tanstack/router-core 1.171.16-pre.0 → 1.171.16

package/skills/router-core/SKILL.md

@@ -5,9 +5,10 @@ description: >-
   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'
+metadata:
+  type: core
+  library: tanstack-router
+  library_version: '1.171.15'
 ---
 
 # TanStack Router Core
@@ -18,6 +19,8 @@ TanStack Router is a type-safe router for React and Solid with built-in SWR cach
 
 > **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.
 
+Use this entry skill to choose one primary sub-skill. Do not load the full catalog. Load a second sub-skill only when the task crosses a real boundary, such as an authenticated loader that needs both `auth-and-guards` and `data-loading`.
+
 ## Sub-Skills
 
 | Task                                               | Sub-Skill                                                                    |
@@ -66,6 +69,22 @@ Need server-side rendering?
   → router-core/ssr
 ```
 
+## Cross-Cutting Completion Checks
+
+For route refactors:
+
+1. Rename or move the route file; do not hand-edit the generated `createFileRoute` path.
+2. Regenerate `routeTree.gen.ts` with the configured Router plugin or CLI.
+3. Update links, redirects, `from` narrowing, params, and tests that reference the old route.
+4. Run type tests and a production build. A typecheck alone does not prove route generation or bundling works.
+
+For response schema changes:
+
+1. Update the source model and shared validation schema.
+2. Update the server function or API serializer so the field exists at runtime.
+3. Update loader and component consumers without casts.
+4. Assert the actual response payload in a unit or integration test. Typechecking cannot catch a serializer that omits the new field.
+
 ## Minimal Working Example
 
 ```tsx
@@ -136,4 +155,4 @@ The plugin auto-generates this string. If you rename a route file, the plugin up
 
 ## 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.
+This skill targets `@tanstack/router-core` v1.171.15. Splat routes use `$` (not `*`); the `*` compat alias will be removed in v2.

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

@@ -1,17 +1,17 @@
 ---
-name: router-core/auth-and-guards
+name: 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'
+metadata:
+  type: sub-skill
+  library: tanstack-router
+  library_version: '1.171.15'
 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
@@ -377,7 +377,7 @@ export const Route = createFileRoute('/_authenticated')({
 
 ### 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.
+A `beforeLoad` redirect protects the **route's UI**, not the **server functions** declared on it. `createServerFn` produces an RPC endpoint reachable directly with its declared HTTP method regardless of which route renders the calling UI. An attacker doesn't have to load `/_authenticated/orders` — they can call this GET RPC endpoint directly.
 
 ```tsx
 // WRONG — handler has no auth check; the route guard doesn't help
@@ -410,6 +410,10 @@ const getMyOrders = createServerFn({ method: 'GET' })
 
 Rule of thumb: every `createServerFn`, server route, or API endpoint that touches user data needs `authMiddleware` (or an equivalent in-handler check). The route guard is for the page experience; the endpoint 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.
 
+### CRITICAL: The anonymous destination can still disclose protected data
+
+Protect the entire anonymous response, not only the API call. A public login or unauthorized page still leaks data if its title, copy, search params, or serialized loader state names the protected user, tenant, record, or resource. Test a direct anonymous request and follow redirects. Assert that the handler rejects before reading private data, no protected loader runs, the final HTML and serialized state contain no protected identity, and the redirect contains only a sanitized relative return URL.
+
 ### HIGH: Auth check in component instead of beforeLoad
 
 Component-level auth checks cause a **flash of protected content** before the redirect:
@@ -435,8 +439,6 @@ export const Route = createFileRoute('/_authenticated/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:
@@ -490,8 +492,6 @@ export const Route = createFileRoute('/_authenticated')({
 
 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

package/skills/router-core/code-splitting/SKILL.md

@@ -1,13 +1,14 @@
 ---
-name: router-core/code-splitting
+name: code-splitting
 description: >-
   Automatic code splitting (autoCodeSplitting), .lazy.tsx convention,
   createLazyFileRoute, createLazyRoute, lazyRouteComponent, getRouteApi
   for typed hooks in split files, codeSplitGroupings per-route override,
   splitBehavior programmatic config, critical vs non-critical properties.
-type: sub-skill
-library: tanstack-router
-library_version: '1.166.2'
+metadata:
+  type: sub-skill
+  library: tanstack-router
+  library_version: '1.171.15'
 requires:
   - router-core
 sources:

package/skills/router-core/data-loading/SKILL.md

@@ -1,14 +1,15 @@
 ---
-name: router-core/data-loading
+name: data-loading
 description: >-
   Route loader option, loaderDeps for cache keys, staleTime/gcTime/
   defaultPreloadStaleTime SWR caching, pendingComponent/pendingMs/
   pendingMinMs, errorComponent/onError/onCatch, beforeLoad, router
   context and createRootRouteWithContext DI pattern, router.invalidate,
   Await component, deferred data loading with unawaited promises.
-type: sub-skill
-library: tanstack-router
-library_version: '1.166.2'
+metadata:
+  type: sub-skill
+  library: tanstack-router
+  library_version: '1.171.15'
 requires:
   - router-core
 sources:
@@ -216,13 +217,29 @@ Route-level context via `beforeLoad`:
 
 ```tsx
 export const Route = createFileRoute('/posts')({
-  beforeLoad: () => ({
-    fetchPosts: () => fetch('/api/posts').then((r) => r.json()),
+  beforeLoad: ({ context }) => ({
+    fetchPosts: context.fetchPosts,
   }),
   loader: ({ context: { fetchPosts } }) => fetchPosts(),
 })
 ```
 
+Keep the implementation SSR-safe when the router is used by TanStack Start. A relative `fetch('/api/posts')` works in a browser event handler, but Node and many server runtimes require an absolute URL during SSR. For app-internal data in Start, call a server function from the loader:
+
+```tsx
+import { createServerFn } from '@tanstack/react-start'
+
+const getPosts = createServerFn({ method: 'GET' }).handler(() => {
+  return db.posts.findMany()
+})
+
+export const Route = createFileRoute('/posts')({
+  loader: () => getPosts(),
+})
+```
+
+Use a server route plus an origin-derived absolute URL only when the HTTP boundary itself is required. Do not hard-code the production origin.
+
 ### Deferred Data Loading
 
 Return unawaited promises from the loader for non-critical data. Use the `Await` component to render them:
@@ -276,19 +293,17 @@ function AddPostButton() {
   const router = useRouter()
 
   const handleAdd = async () => {
-    await fetch('/api/posts', { method: 'POST', body: '...' })
-    router.invalidate()
+    await createPost({ title: 'New post' })
+    await router.invalidate({ sync: true })
   }
 
   return <button onClick={handleAdd}>Add Post</button>
 }
 ```
 
-For synchronous invalidation (wait until loaders finish):
+Use `await router.invalidate({ sync: true })` when the next step requires refreshed loader data.
 
-```tsx
-await router.invalidate({ sync: true })
-```
+Treat the mutation and invalidation as one workflow. The mutation must persist before invalidation starts, and the loader must read from the same authoritative store. Verify create, update, and delete through the rendered route, including a fresh reload; local component state can hide a stale loader or non-persistent write.
 
 ### Error Handling
 
@@ -361,16 +376,13 @@ export const Route = createFileRoute('/posts')({
   },
 })
 
-// CORRECT — loaders run in the browser, use fetch or API calls
+// CORRECT for an SPA — use a client-safe API helper
 export const Route = createFileRoute('/posts')({
-  loader: async () => {
-    const res = await fetch('/api/posts')
-    return res.json()
-  },
+  loader: () => fetchPosts(),
 })
 ```
 
-Do NOT put database queries, filesystem access, or server-only code in loaders unless you are using TanStack Start server functions.
+Do NOT put database queries, filesystem access, or server-only code directly in loaders. In TanStack Start, put that work in a server function and call the function from the loader. Do not use a relative `fetch('/api/...')` in an SSR loader.
 
 ### MEDIUM: Not understanding staleTime default is 0
 

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

@@ -1,14 +1,15 @@
 ---
-name: router-core/navigation
+name: navigation
 description: >-
   Link component, useNavigate, Navigate component, router.navigate,
   ToOptions/NavigateOptions/LinkOptions, from/to relative navigation,
   activeOptions/activeProps, preloading (intent/viewport/render),
   preloadDelay, navigation blocking (useBlocker, Block), createLink,
   linkOptions helper, scroll restoration, MatchRoute.
-type: sub-skill
-library: tanstack-router
-library_version: '1.166.2'
+metadata:
+  type: sub-skill
+  library: tanstack-router
+  library_version: '1.171.15'
 requires:
   - router-core
 sources:

package/skills/router-core/not-found-and-errors/SKILL.md

@@ -1,13 +1,14 @@
 ---
-name: router-core/not-found-and-errors
+name: not-found-and-errors
 description: >-
   notFound() function, notFoundComponent, defaultNotFoundComponent,
   notFoundMode (fuzzy/root), errorComponent, CatchBoundary,
   CatchNotFound, isNotFound, NotFoundRoute (deprecated), route
   masking (mask option, createRouteMask, unmaskOnReload).
-type: sub-skill
-library: tanstack-router
-library_version: '1.166.2'
+metadata:
+  type: sub-skill
+  library: tanstack-router
+  library_version: '1.171.15'
 requires:
   - router-core
 sources:

package/skills/router-core/path-params/SKILL.md

@@ -1,13 +1,14 @@
 ---
-name: router-core/path-params
+name: path-params
 description: >-
   Dynamic path segments ($paramName), splat routes ($ / _splat),
   optional params ({-$paramName}), prefix/suffix patterns ({$param}.ext),
   useParams, params.parse/stringify, pathParamsAllowedCharacters,
   i18n locale patterns.
-type: sub-skill
-library: tanstack-router
-library_version: '1.166.2'
+metadata:
+  type: sub-skill
+  library: tanstack-router
+  library_version: '1.171.15'
 requires:
   - router-core
 sources:

package/skills/router-core/search-params/SKILL.md

@@ -1,13 +1,14 @@
 ---
-name: router-core/search-params
+name: search-params
 description: >-
   validateSearch, search param validation with Zod/Valibot/ArkType adapters,
   fallback(), search middlewares (retainSearchParams, stripSearchParams),
   custom serialization (parseSearch, stringifySearch), search param
   inheritance, loaderDeps for cache keys, reading and writing search params.
-type: sub-skill
-library: tanstack-router
-library_version: '1.166.2'
+metadata:
+  type: sub-skill
+  library: tanstack-router
+  library_version: '1.171.15'
 requires:
   - router-core
 sources:

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

@@ -1,5 +1,5 @@
 ---
-name: router-core/ssr
+name: ssr
 description: >-
   Non-streaming and streaming SSR, RouterClient/RouterServer,
   renderRouterToString/renderRouterToStream, createRequestHandler,
@@ -7,9 +7,10 @@ description: >-
   components, head route option (meta/links/styles/scripts),
   ScriptOnce, automatic loader dehydration/hydration, memory
   history on server, data serialization, document head management.
-type: sub-skill
-library: tanstack-router
-library_version: '1.166.2'
+metadata:
+  type: sub-skill
+  library: tanstack-router
+  library_version: '1.171.15'
 requires:
   - router-core
   - router-core/data-loading

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

@@ -1,14 +1,15 @@
 ---
-name: router-core/type-safety
+name: type-safety
 description: >-
   Full type inference philosophy (never cast, never annotate inferred
   values), Register module declaration, from narrowing on hooks and
   Link, strict:false for shared components, getRouteApi for code-split
   typed access, addChildren with object syntax for TS perf, LinkProps
   and ValidateLinkOptions type utilities, as const satisfies pattern.
-type: sub-skill
-library: tanstack-router
-library_version: '1.166.2'
+metadata:
+  type: sub-skill
+  library: tanstack-router
+  library_version: '1.171.15'
 requires:
   - router-core
 sources:
@@ -489,4 +490,10 @@ 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.
 
+### 6. CRITICAL: Treating typecheck as proof of runtime schema propagation
+
+Types can say a field exists while a database projection, API serializer, or server function omits it. When adding or renaming a field, trace the value through storage, validation, handler output, loader data, and rendered UI. Do not cast the response to the desired type.
+Add a runtime assertion against the real handler or serialized response, such as `expect(await getOrder({ data: { id } })).toMatchObject({ totalCents: 2599 })`.
+Then run the route-level test and production build. The type test remains necessary, but it is not the runtime contract test.
+
 See also: router-core (Register setup), router-core/navigation (from narrowing), router-core/code-splitting (getRouteApi).

package/src/link.ts

@@ -671,13 +671,15 @@ export interface LinkOptionsProps {
   /**
    * The preloading strategy for this link
    * - `false` - No preloading
-   * - `'intent'` - Preload the linked route on hover and cache it for this many milliseconds in hopes that the user will eventually navigate there.
+   * - `'intent'` - Preload the linked route when the user focuses, hovers over, or touches the link
    * - `'viewport'` - Preload the linked route when it enters the viewport
+   * - `'render'` - Preload the linked route as soon as it renders
    */
   preload?: false | 'intent' | 'viewport' | 'render'
   /**
-   * When a preload strategy is set, this delays the preload by this many milliseconds.
-   * If the user exits the link before this delay, the preload will be cancelled.
+   * When the intent preload strategy is set, this delays focus and hover
+   * preloading by this many milliseconds. Touch intent preloads immediately.
+   * If focus or hover exits before this delay, the preload will be cancelled.
    */
   preloadDelay?: number
   /**