react-router 7.2.0-pre.6 → 7.3.0-pre.0

package/CHANGELOG.md

@@ -1,45 +1,265 @@
 # `react-router`
 
-## 7.2.0-pre.6
+## 7.3.0-pre.0
 
-## 7.2.0-pre.5
+### Minor Changes
+
+- Add `fetcherKey` as a parameter to `patchRoutesOnNavigation` ([#13061](https://github.com/remix-run/react-router/pull/13061))
+
+  - In framework mode, Lazy Route Discovery will now detect manifest version mismatches after a new deploy
+  - On navigations to undiscovered routes, this mismatch will trigger a document reload of the destination path
+  - On `fetcher` calls to undiscovered routes, this mismatch will trigger a document reload of the current path
 
 ### Patch Changes
 
-- [REMOVE] Fix prerender calls to serverLoader from clientLoader ([#13047](https://github.com/remix-run/react-router/pull/13047))
+- Skip resource route flow in dev server in SPA mode ([#13113](https://github.com/remix-run/react-router/pull/13113))
+- Support middleware on routes (unstable) ([#12941](https://github.com/remix-run/react-router/pull/12941))
 
-## 7.2.0-pre.4
+  Middleware is implemented behind a `future.unstable_middleware` flag. To enable, you must enable the flag and the types in your `react-router-config.ts` file:
 
-## 7.2.0-pre.3
+  ```ts
+  import type { Config } from "@react-router/dev/config";
+  import type { Future } from "react-router";
 
-### Patch Changes
+  declare module "react-router" {
+    interface Future {
+      unstable_middleware: true; // 👈 Enable middleware types
+    }
+  }
 
-- Add `unstable_SerializesTo` brand type for library authors to register types serializable by React Router's streaming format (`turbo-stream`) ([`ab5b05b02`](https://github.com/remix-run/react-router/commit/ab5b05b02f99f062edb3c536c392197c88eb6c77))
+  export default {
+    future: {
+      unstable_middleware: true, // 👈 Enable middleware
+    },
+  } satisfies Config;
+  ```
 
-## 7.2.0-pre.2
+  ⚠️ Middleware is unstable and should not be adopted in production. There is at least one known de-optimization in route module loading for `clientMiddleware` that we will be addressing this before a stable release.
 
-### Patch Changes
+  ⚠️ Enabling middleware contains a breaking change to the `context` parameter passed to your `loader`/`action` functions - see below for more information.
 
-- Properly handle revalidations to across a prerender/SPA boundary ([#13021](https://github.com/remix-run/react-router/pull/13021))
+  Once enabled, routes can define an array of middleware functions that will run sequentially before route handlers run. These functions accept the same parameters as `loader`/`action` plus an additional `next` parameter to run the remaining data pipeline. This allows middlewares to perform logic before and after handlers execute.
 
-  - In "hybrid" applications where some routes are pre-rendered and some are served from a SPA fallback, we need to avoid making `.data` requests if the path wasn't pre-rendered because the request will 404
-  - We don't know all the pre-rendered paths client-side, however:
-    - All `loader` data in `ssr:false` mode is static because it's generated at build time
-    - A route must use a `clientLoader` to do anything dynamic
-    - Therefore, if a route only has a `loader` and not a `clientLoader`, we disable revalidation by default because there is no new data to retrieve
-    - We short circuit and skip single fetch `.data` request logic if there are no server loaders with `shouldLoad=true` in our single fetch `dataStrategy`
-    - This ensures that the route doesn't cause a `.data` request that would 404 after a submission
+  ```tsx
+  // Framework mode
+  export const unstable_middleware = [serverLogger, serverAuth]; // server
+  export const unstable_clientMiddleware = [clientLogger]; // client
+
+  // Library mode
+  const routes = [
+    {
+      path: "/",
+      // Middlewares are client-side for library mode SPA's
+      unstable_middleware: [clientLogger, clientAuth],
+      loader: rootLoader,
+      Component: Root,
+    },
+  ];
+  ```
 
-- Error at build time in `ssr:false` + `prerender` apps for the edge case scenario of: ([#13021](https://github.com/remix-run/react-router/pull/13021))
+  Here's a simple example of a client-side logging middleware that can be placed on the root route:
 
-  - A parent route has only a `loader` (does not have a `clientLoader`)
-  - The parent route is pre-rendered
-  - The parent route has children routes which are not prerendered
-  - This means that when the child paths are loaded via the SPA fallback, the parent won't have any `loaderData` because there is no server on which to run the `loader`
-  - This can be resolved by either adding a parent `clientLoader` or pre-rendering the child paths
-  - If you add a `clientLoader`, calling the `serverLoader()` on non-prerendered paths will throw a 404
+  ```tsx
+  const clientLogger: Route.unstable_ClientMiddlewareFunction = async (
+    { request },
+    next
+  ) => {
+    let start = performance.now();
+
+    // Run the remaining middlewares and all route loaders
+    await next();
+
+    let duration = performance.now() - start;
+    console.log(`Navigated to ${request.url} (${duration}ms)`);
+  };
+  ```
+
+  Note that in the above example, the `next`/`middleware` functions don't return anything. This is by design as on the client there is no "response" to send over the network like there would be for middlewares running on the server. The data is all handled behind the scenes by the stateful `router`.
+
+  For a server-side middleware, the `next` function will return the HTTP `Response` that React Router will be sending across the wire, thus giving you a chance to make changes as needed. You may throw a new response to short circuit and respond immediately, or you may return a new or altered response to override the default returned by `next()`.
+
+  ```tsx
+  const serverLogger: Route.unstable_MiddlewareFunction = async (
+    { request, params, context },
+    next
+  ) => {
+    let start = performance.now();
+
+    // 👇 Grab the response here
+    let res = await next();
+
+    let duration = performance.now() - start;
+    console.log(`Navigated to ${request.url} (${duration}ms)`);
+
+    // 👇 And return it here (optional if you don't modify the response)
+    return res;
+  };
+  ```
+
+  You can throw a `redirect` from a middleware to short circuit any remaining processing:
+
+  ```tsx
+  import { sessionContext } from "../context";
+  const serverAuth: Route.unstable_MiddlewareFunction = (
+    { request, params, context },
+    next
+  ) => {
+    let session = context.get(sessionContext);
+    let user = session.get("user");
+    if (!user) {
+      session.set("returnTo", request.url);
+      throw redirect("/login", 302);
+    }
+  };
+  ```
 
-## 7.2.0-pre.1
+  _Note that in cases like this where you don't need to do any post-processing you don't need to call the `next` function or return a `Response`._
+
+  Here's another example of using a server middleware to detect 404s and check the CMS for a redirect:
+
+  ```tsx
+  const redirects: Route.unstable_MiddlewareFunction = async ({
+    request,
+    next,
+  }) => {
+    // attempt to handle the request
+    let res = await next();
+
+    // if it's a 404, check the CMS for a redirect, do it last
+    // because it's expensive
+    if (res.status === 404) {
+      let cmsRedirect = await checkCMSRedirects(request.url);
+      if (cmsRedirect) {
+        throw redirect(cmsRedirect, 302);
+      }
+    }
+
+    return res;
+  };
+  ```
+
+  **`context` parameter**
+
+  When middleware is enabled, your application will use a different type of `context` parameter in your loaders and actions to provide better type safety. Instead of `AppLoadContext`, `context` will now be an instance of `ContextProvider` that you can use with type-safe contexts (similar to `React.createContext`):
+
+  ```ts
+  import { unstable_createContext } from "react-router";
+  import { Route } from "./+types/root";
+  import type { Session } from "./sessions.server";
+  import { getSession } from "./sessions.server";
+
+  let sessionContext = unstable_createContext<Session>();
+
+  const sessionMiddleware: Route.unstable_MiddlewareFunction = ({
+    context,
+    request,
+  }) => {
+    let session = await getSession(request);
+    context.set(sessionContext, session);
+    //                          ^ must be of type Session
+  };
+
+  // ... then in some downstream middleware
+  const loggerMiddleware: Route.unstable_MiddlewareFunction = ({
+    context,
+    request,
+  }) => {
+    let session = context.get(sessionContext);
+    //  ^ typeof Session
+    console.log(session.get("userId"), request.method, request.url);
+  };
+
+  // ... or some downstream loader
+  export function loader({ context }: Route.LoaderArgs) {
+    let session = context.get(sessionContext);
+    let profile = await getProfile(session.get("userId"));
+    return { profile };
+  }
+  ```
+
+  If you are using a custom server with a `getLoadContext` function, the return value for initial context values passed from the server adapter layer is no longer an object and should now return an `unstable_InitialContext` (`Map<RouterContext, unknown>`):
+
+  ```ts
+  let adapterContext = unstable_createContext<MyAdapterContext>();
+
+  function getLoadContext(req, res): unstable_InitialContext {
+    let map = new Map();
+    map.set(adapterContext, getAdapterContext(req));
+    return map;
+  }
+  ```
+
+- Fix types for loaderData and actionData that contained `Record`s ([#13139](https://github.com/remix-run/react-router/pull/13139))
+
+  UNSTABLE(BREAKING):
+
+  `unstable_SerializesTo` added a way to register custom serialization types in Single Fetch for other library and framework authors like Apollo.
+  It was implemented with branded type whose branded property that was made optional so that casting arbitrary values was easy:
+
+  ```ts
+  // without the brand being marked as optional
+  let x1 = 42 as unknown as unstable_SerializesTo<number>;
+  //          ^^^^^^^^^^
+
+  // with the brand being marked as optional
+  let x2 = 42 as unstable_SerializesTo<number>;
+  ```
+
+  However, this broke type inference in `loaderData` and `actionData` for any `Record` types as those would now (incorrectly) match `unstable_SerializesTo`.
+  This affected all users, not just those that depended on `unstable_SerializesTo`.
+  To fix this, the branded property of `unstable_SerializesTo` is marked as required instead of optional.
+
+  For library and framework authors using `unstable_SerializesTo`, you may need to add `as unknown` casts before casting to `unstable_SerializesTo`.
+
+- Fix single fetch `_root.data` requests when a `basename` is used ([#12898](https://github.com/remix-run/react-router/pull/12898))
+- Add `context` support to client side data routers (unstable) ([#12941](https://github.com/remix-run/react-router/pull/12941))
+
+  Your application `loader` and `action` functions on the client will now receive a `context` parameter. This is an instance of `unstable_RouterContextProvider` that you use with type-safe contexts (similar to `React.createContext`) and is most useful with the corresponding `middleware`/`clientMiddleware` API's:
+
+  ```ts
+  import { unstable_createContext } from "react-router";
+
+  type User = {
+    /*...*/
+  };
+
+  let userContext = unstable_createContext<User>();
+
+  function sessionMiddleware({ context }) {
+    let user = await getUser();
+    context.set(userContext, user);
+  }
+
+  // ... then in some downstream loader
+  function loader({ context }) {
+    let user = context.get(userContext);
+    let profile = await getProfile(user.id);
+    return { profile };
+  }
+  ```
+
+  Similar to server-side requests, a fresh `context` will be created per navigation (or `fetcher` call). If you have initial data you'd like to populate in the context for every request, you can provide an `unstable_getContext` function at the root of your app:
+
+  - Library mode - `createBrowserRouter(routes, { unstable_getContext })`
+  - Framework mode - `<HydratedRouter unstable_getContext>`
+
+  This function should return an value of type `unstable_InitialContext` which is a `Map<unstable_RouterContext, unknown>` of context's and initial values:
+
+  ```ts
+  const loggerContext = unstable_createContext<(...args: unknown[]) => void>();
+
+  function logger(...args: unknown[]) {
+    console.log(new Date.toISOString(), ...args);
+  }
+
+  function unstable_getContext() {
+    let map = new Map();
+    map.set(loggerContext, logger);
+    return map;
+  }
+  ```
+
+## 7.2.0
 
 ### Minor Changes
 
@@ -73,12 +293,31 @@
   To be consistent with runtime behavior, the generated types now correctly model the "last one wins" semantics of path parameters.
   So `/a/1/b/2/c/3` now generates a type like `{ id: 3 }`.
 
-## 7.2.0-pre.0
+- Don't apply Single Fetch revalidation de-optimization when in SPA mode since there is no server HTTP request ([#12948](https://github.com/remix-run/react-router/pull/12948))
 
-### Patch Changes
+- Properly handle revalidations to across a prerender/SPA boundary ([#13021](https://github.com/remix-run/react-router/pull/13021))
+
+  - In "hybrid" applications where some routes are pre-rendered and some are served from a SPA fallback, we need to avoid making `.data` requests if the path wasn't pre-rendered because the request will 404
+  - We don't know all the pre-rendered paths client-side, however:
+    - All `loader` data in `ssr:false` mode is static because it's generated at build time
+    - A route must use a `clientLoader` to do anything dynamic
+    - Therefore, if a route only has a `loader` and not a `clientLoader`, we disable revalidation by default because there is no new data to retrieve
+    - We short circuit and skip single fetch `.data` request logic if there are no server loaders with `shouldLoad=true` in our single fetch `dataStrategy`
+    - This ensures that the route doesn't cause a `.data` request that would 404 after a submission
+
+- Error at build time in `ssr:false` + `prerender` apps for the edge case scenario of: ([#13021](https://github.com/remix-run/react-router/pull/13021))
+
+  - A parent route has only a `loader` (does not have a `clientLoader`)
+  - The parent route is pre-rendered
+  - The parent route has children routes which are not prerendered
+  - This means that when the child paths are loaded via the SPA fallback, the parent won't have any `loaderData` because there is no server on which to run the `loader`
+  - This can be resolved by either adding a parent `clientLoader` or pre-rendering the child paths
+  - If you add a `clientLoader`, calling the `serverLoader()` on non-prerendered paths will throw a 404
 
-- Don't apply Single Fetch revalidation de-optimization when in SPA mode since there is no server HTTP request ([#12948](https://github.com/remix-run/react-router/pull/12948))
 - Add unstable support for splitting route modules in framework mode via `future.unstable_splitRouteModules` ([#11871](https://github.com/remix-run/react-router/pull/11871))
+
+- Add `unstable_SerializesTo` brand type for library authors to register types serializable by React Router's streaming format (`turbo-stream`) ([`ab5b05b02`](https://github.com/remix-run/react-router/commit/ab5b05b02f99f062edb3c536c392197c88eb6c77))
+
 - Align dev server behavior with static file server behavior when `ssr:false` is set ([#12948](https://github.com/remix-run/react-router/pull/12948))
 
   - When no `prerender` config exists, only SSR down to the root `HydrateFallback` (SPA Mode)
@@ -86,6 +325,7 @@
   - Return a 404 on `.data` requests to non-pre-rendered paths
 
 - Improve prefetch performance of CSS side effects in framework mode ([#12889](https://github.com/remix-run/react-router/pull/12889))
+
 - Disable Lazy Route Discovery for all `ssr:false` apps and not just "SPA Mode" because there is no runtime server to serve the search-param-configured `__manifest` requests ([#12894](https://github.com/remix-run/react-router/pull/12894))
 
   - We previously only disabled this for "SPA Mode" which is `ssr:false` and no `prerender` config but we realized it should apply to all `ssr:false` apps, including those prerendering multiple pages