Merge branch 'main' into release-next

Author: brophdawg11

contributors.yml

@@ -47,7 +47,9 @@
 - bhbs
 - bilalk711
 - bobziroll
+- bravo-kernel
 - Brendonovich
+- briankb
 - BrianT1414
 - brockross
 - brookslybrand
@@ -241,6 +243,7 @@
 - printfn
 - promet99
 - proshunsuke
+- pwdcd
 - pyitphyoaung
 - refusado
 - reyronald
@@ -313,6 +316,7 @@
 - valerii15298
 - ValiantCat
 - vdusart
+- VictorElHajj
 - vijaypushkin
 - vikingviolinist
 - vishwast03

decisions/0012-type-inference.md

@@ -278,7 +278,7 @@ This was an additional indication that maybe a TypeScript plugin was not the rig
 
 ## Summary
 
-By leaning into automated typegen within a TypeScript plugin, we radically simplify React Router's runtime APIs while providing strong type inference across the entire framework.
+By leaning into automated typegen, we radically simplify React Router's runtime APIs while providing strong type inference across the entire framework.
 We can continue to support programmatic routing _and_ file-based routing in `routes.ts` while providing typesafety with the same approach and same code path.
 We can design our runtime APIs without introducing bespoke ways to inform TypeScript of the route hierarchy.
 

docs/explanation/special-files.md

@@ -248,7 +248,7 @@ export default function handleRequest(...) {
       { /* ... */ }
     );
 
-    // Abort the streaming render pass after 11 seconds soto allow the rejected
+    // Abort the streaming render pass after 11 seconds so to allow the rejected
     // boundaries to be flushed
     setTimeout(abort, streamTimeout + 1000);
   });

docs/how-to/client-data.md

@@ -0,0 +1,194 @@
+---
+title: Client Data
+---
+
+# Client Data
+
+You can fetch and mutate data directly in the browser using `clientLoader` and `clientAction` functions.
+
+These functions are the primary mechanism for data handling when using [SPA mode][spa]. This guide demonstrates common use cases for leveraging client data in Server-Side Rendering (SSR).
+
+## Skip the Server Hop
+
+When using React Router with a Backend-For-Frontend (BFF) architecture, you might want to bypass the React Router server and communicate directly with your backend API. This approach requires proper authentication handling and assumes no CORS restrictions. Here's how to implement this:
+
+1. Load the data from server `loader` on the document load
+2. Load the data from the `clientLoader` on all subsequent loads
+
+In this scenario, React Router will _not_ call the `clientLoader` on hydration - and will only call it on subsequent navigations.
+
+```tsx lines=[4,11]
+export async function loader({
+  request,
+}: Route.LoaderArgs) {
+  const data = await fetchApiFromServer({ request }); // (1)
+  return data;
+}
+
+export async function clientLoader({
+  request,
+}: Route.ClientLoaderArgs) {
+  const data = await fetchApiFromClient({ request }); // (2)
+  return data;
+}
+```
+
+## Fullstack State
+
+Sometimes you need to combine data from both the server and browser (like IndexedDB or browser SDKs) before rendering a component. Here's how to implement this pattern:
+
+1. Load the partial data from server `loader` on the document load
+2. Export a [`HydrateFallback`][hydratefallback] component to render during SSR because we don't yet have a full set of data
+3. Set `clientLoader.hydrate = true`, this instructs React Router to call the clientLoader as part of initial document hydration
+4. Combine the server data with the client data in `clientLoader`
+
+```tsx lines=[4-6,19-20,23,26]
+export async function loader({
+  request,
+}: Route.LoaderArgs) {
+  const partialData = await getPartialDataFromDb({
+    request,
+  }); // (1)
+  return partialData;
+}
+
+export async function clientLoader({
+  request,
+  serverLoader,
+}: Route.ClientLoaderArgs) {
+  const [serverData, clientData] = await Promise.all([
+    serverLoader(),
+    getClientData(request),
+  ]);
+  return {
+    ...serverData, // (4)
+    ...clientData, // (4)
+  };
+}
+clientLoader.hydrate = true as const; // (3)
+
+export function HydrateFallback() {
+  return <p>Skeleton rendered during SSR</p>; // (2)
+}
+
+export default function Component({
+  // This will always be the combined set of server + client data
+  loaderData,
+}: Route.ComponentProps) {
+  return <>...</>;
+}
+```
+
+## Choosing Server or Client Data Loading
+
+You can mix data loading strategies across your application, choosing between server-only or client-only data loading for each route. Here's how to implement both approaches:
+
+1. Export a `loader` when you want to use server data
+2. Export `clientLoader` and a `HydrateFallback` when you want to use client data
+
+A route that only depends on a server loader looks like this:
+
+```tsx filename=app/routes/server-data-route.tsx
+export async function loader({
+  request,
+}: Route.LoaderArgs) {
+  const data = await getServerData(request);
+  return data;
+}
+
+export default function Component({
+  loaderData, // (1) - server data
+}: Route.ComponentProps) {
+  return <>...</>;
+}
+```
+
+A route that only depends on a client loader looks like this.
+
+```tsx filename=app/routes/client-data-route.tsx
+export async function clientLoader({
+  request,
+}: Route.ClientLoaderArgs) {
+  const clientData = await getClientData(request);
+  return clientData;
+}
+// Note: you do not have to set this explicitly - it is implied if there is no `loader`
+clientLoader.hydrate = true;
+
+// (2)
+export function HydrateFallback() {
+  return <p>Skeleton rendered during SSR</p>;
+}
+
+export default function Component({
+  loaderData, // (2) - client data
+}: Route.ComponentProps) {
+  return <>...</>;
+}
+```
+
+## Client-Side Caching
+
+You can implement client-side caching (using memory, localStorage, etc.) to optimize server requests. Here's a pattern that demonstrates cache management:
+
+1. Load the data from server `loader` on the document load
+2. Set `clientLoader.hydrate = true` to prime the cache
+3. Load subsequent navigations from the cache via `clientLoader`
+4. Invalidate the cache in your `clientAction`
+
+Note that since we are not exporting a `HydrateFallback` component, we will SSR the route component and then run the `clientLoader` on hydration, so it's important that your `loader` and `clientLoader` return the same data on initial load to avoid hydration errors.
+
+```tsx lines=[4,26,32,39,46]
+export async function loader({
+  request,
+}: Route.LoaderArgs) {
+  const data = await getDataFromDb({ request }); // (1)
+  return data;
+}
+
+export async function action({
+  request,
+}: Route.ActionArgs) {
+  await saveDataToDb({ request });
+  return { ok: true };
+}
+
+let isInitialRequest = true;
+
+export async function clientLoader({
+  request,
+  serverLoader,
+}: Route.ClientLoaderArgs) {
+  const cacheKey = generateKey(request);
+
+  if (isInitialRequest) {
+    isInitialRequest = false;
+    const serverData = await serverLoader();
+    cache.set(cacheKey, serverData); // (2)
+    return serverData;
+  }
+
+  const cachedData = await cache.get(cacheKey);
+  if (cachedData) {
+    return cachedData; // (3)
+  }
+
+  const serverData = await serverLoader();
+  cache.set(cacheKey, serverData);
+  return serverData;
+}
+clientLoader.hydrate = true; // (2)
+
+export async function clientAction({
+  request,
+  serverAction,
+}: Route.ClientActionArgs) {
+  const cacheKey = generateKey(request);
+  cache.delete(cacheKey); // (4)
+  const serverData = await serverAction();
+  return serverData;
+}
+```
+
+[spa]: ../how-to/spa
+[hydratefallback]: ../start/framework/route-module#hydratefallback

docs/how-to/file-route-conventions.md

@@ -23,6 +23,18 @@ import { flatRoutes } from "@react-router/fs-routes";
 export default flatRoutes() satisfies RouteConfig;
 ```
 
+Any modules in the `app/routes` directory will become routes in your application by default.
+The `ignoredRouteFiles` option allows you to specify files that should not be included as routes:
+
+```tsx filename=app/routes.ts
+import { type RouteConfig } from "@react-router/dev/routes";
+import { flatRoutes } from "@react-router/fs-routes";
+
+export default flatRoutes({
+  ignoredRouteFiles: ["home.tsx"],
+}) satisfies RouteConfig;
+```
+
 This will look for routes in the `app/routes` directory by default, but this can be configured via the `rootDirectory` option which is relative to your app directory:
 
 ```tsx filename=app/routes.ts
@@ -38,7 +50,7 @@ The rest of this guide will assume you're using the default `app/routes` directo
 
 ## Basic Routes
 
-Any modules in the `app/routes` directory will become routes in your application. The filename maps to the route's URL pathname, except for `_index.tsx` which is the [index route][index_route] for the [root route][root_route]. You can use `.js`, `.jsx`, `.ts` or `.tsx` file extensions.
+The filename maps to the route's URL pathname, except for `_index.tsx` which is the [index route][index_route] for the [root route][root_route]. You can use `.js`, `.jsx`, `.ts` or `.tsx` file extensions.
 
 ```text lines=[3-4]
 app/

docs/how-to/headers.md

@@ -58,6 +58,8 @@ export function headers({
 }
 ```
 
+One notable exception is `Set-Cookie` headers, which are automatically preserved from `headers`, `loader`, and `action` in parent routes, even without exporting `headers` from the child route.
+
 ## Merging with parent headers
 
 Consider these nested routes

docs/how-to/spa.md

@@ -63,7 +63,7 @@ If you're getting 404s at valid routes for your app, it's likely you need to con
 
 ## Important Note
 
-Typical Single Pages apps send a mostly blank index.html template with little more than an empty `<div id="root"></div>`.
+Typical Single Pages apps send a mostly blank `index.html` template with little more than an empty `<div id="root"></div>`.
 
 In contrast `react-router build` (with server rendering disabled) pre-renders your root and index routes. This means you can:
 

docs/start/framework/data-loading.md

@@ -9,6 +9,8 @@ Data is provided to the route component from `loader` and `clientLoader`.
 
 Loader data is automatically serialized from loaders and deserialized in components. In addition to primitive values like strings and numbers, loaders can return promises, maps, sets, dates and more.
 
+The type for the `loaderData` prop is [automatically generated][type-safety].
+
 ## Client Data Loading
 
 `clientLoader` is used to fetch data on the client. This is useful for pages or full projects that you'd prefer to fetch data from the browser only.
@@ -25,6 +27,11 @@ export async function clientLoader({
   return product;
 }
 
+// HydrateFallback is rendered while the client loader is running
+export function HydrateFallback() {
+  return <div>Loading...</div>;
+}
+
 export default function Product({
   loaderData,
 }: Route.ComponentProps) {
@@ -124,10 +131,11 @@ export async function loader({ params }: Route.LoaderArgs) {
 }
 
 export async function clientLoader({
+  serverLoader,
   params,
-}: Route.ClientLoader) {
+}: Route.ClientLoaderArgs) {
   const res = await fetch(`/api/products/${params.pid}`);
-  return res.json();
+  return { ...serverData, ...res.json() };
 }
 
 export default function Product({
@@ -144,13 +152,39 @@ export default function Product({
 }
 ```
 
+You can also force the client loader to run during hydration and before the page renders by setting the `hydrate` property on the function. In this situation you will want to render a `HydrateFallback` component to show a fallback UI while the client loader runs.
+
+```tsx filename=app/product.tsx
+export async function loader() {
+  /* ... */
+}
+
+export async function clientLoader() {
+  /* ... */
+}
+
+// force the client loader to run during hydration
+clientLoader.hydrate = true as const; // `as const` for type inference
+
+export function HydrateFallback() {
+  return <div>Loading...</div>;
+}
+
+export default function Product() {
+  /* ... */
+}
+```
+
 ---
 
 Next: [Actions](./actions)
 
 See also:
 
 - [Streaming with Suspense](../../how-to/suspense)
+- [Client Data](../../how-to/client-data)
+- [Using Fetchers](../../how-to/fetchers#loading-data)
 
 [advanced_data_fetching]: ../tutorials/advanced-data-fetching
 [data]: ../../api/react-router/data
+[type-safety]: ../../explanation/type-safety

docs/start/framework/routing.md

@@ -49,7 +49,18 @@ export default [
 ] satisfies RouteConfig;
 ```
 
-If you prefer to define your routes via file naming conventions rather than configuration, the `@react-router/fs-routes` package provides a [file system routing convention.][file-route-conventions]
+If you prefer to define your routes via file naming conventions rather than configuration, the `@react-router/fs-routes` package provides a [file system routing convention][file-route-conventions]. You can even combine different routing conventions if you like:
+
+```ts filename=app/routes.ts
+import { type RouteConfig, route } from "@react-router/dev/routes";
+import { flatRoutes } from "@react-router/fs-routes";
+
+export default = [
+  route("/", "./home.tsx"),
+
+  ...await flatRoutes(),
+] satisfies RouteConfig;
+```
 
 ## Route Modules
 
@@ -263,6 +274,8 @@ async function loader({ params }: LoaderArgs) {
 }
 ```
 
+You should ensure that all dynamic segments in a given path are unique. Otherwise, as the `params` object is populated - latter dynamic segment values will override earlier values.
+
 ## Optional Segments
 
 You can make a route segment optional by adding a `?` to the end of the segment.

docs/start/library/routing.md

@@ -168,6 +168,8 @@ export default function Team() {
 }
 ```
 
+You should ensure that all dynamic segments in a given path are unique. Otherwise, as the `params` object is populated - latter dynamic segment values will override earlier values.
+
 ## Optional Segments
 
 You can make a route segment optional by adding a `?` to the end of the segment.