feat(react-router): add loaderData and deprecate data where possible (#14047)

Author: MichaelDeBoey

.changeset/rare-pears-walk.md

@@ -0,0 +1,7 @@
+---
+"react-router": minor
+---
+
+Add `loaderData` arguments/properties alongside existing `data` arguments/properties to provide consistency and clarity between `loaderData` and `actionData` across the board
+ - Updated types: `Route.MetaArgs`, `Route.MetaMatch`, `MetaArgs`, `MetaMatch`, `Route.ComponentProps.matches`, `UIMatch`
+ - `@deprecated` warnings have been added to the existing `data` properties to point users to new `loaderData` properties, in preparation for removing the `data` properties in a future major release

integration/catch-boundary-test.ts

@@ -255,7 +255,13 @@ test.describe("ErrorBoundary (thrown responses)", () => {
 
     // Root loader data sticks around from previous load
     let expected = JSON.stringify([
-      { id: "root", pathname: "", params: {}, data: { data: "ROOT LOADER" } },
+      {
+        id: "root",
+        pathname: "",
+        params: {},
+        data: { data: "ROOT LOADER" },
+        loaderData: { data: "ROOT LOADER" },
+      },
     ]);
     expect(await app.getHtml("#matches")).toContain(expected);
   });

integration/matches-test.ts

@@ -109,6 +109,7 @@ test.describe("useMatches", () => {
     "pathname": "/",
     "params": {},
     "data": "ROOT",
+    "loaderData": "ROOT",
     "handle": {
       "stuff": "root handle"
     }
@@ -118,6 +119,7 @@ test.describe("useMatches", () => {
     "pathname": "/",
     "params": {},
     "data": "INDEX",
+    "loaderData": "INDEX",
     "handle": {
       "stuff": "index handle"
     }
@@ -135,6 +137,7 @@ test.describe("useMatches", () => {
     "pathname": "/",
     "params": {},
     "data": "ROOT",
+    "loaderData": "ROOT",
     "handle": {
       "stuff": "root handle"
     }
@@ -144,6 +147,7 @@ test.describe("useMatches", () => {
     "pathname": "/",
     "params": {},
     "data": "INDEX",
+    "loaderData": "INDEX",
     "handle": {
       "stuff": "index handle"
     }
@@ -164,6 +168,7 @@ test.describe("useMatches", () => {
     "pathname": "/",
     "params": {},
     "data": "ROOT",
+    "loaderData": "ROOT",
     "handle": {
       "stuff": "root handle"
     }
@@ -173,6 +178,7 @@ test.describe("useMatches", () => {
     "pathname": "/about",
     "params": {},
     "data": "ABOUT",
+    "loaderData": "ABOUT",
     "handle": {
       "stuff": "about handle"
     }

packages/react-router/__tests__/data-memory-router-test.tsx

@@ -812,13 +812,15 @@ describe("createMemoryRouter", () => {
     expect(spy).toHaveBeenCalledWith("Layout", [
       {
         data: undefined,
+        loaderData: undefined,
         handle: undefined,
         id: "0",
         params: {},
         pathname: "/",
       },
       {
         data: "BAR LOADER",
+        loaderData: "BAR LOADER",
         handle: {
           key: "value",
         },

packages/react-router/__tests__/dom/data-static-router-test.tsx

@@ -115,6 +115,9 @@ describe("A <StaticRouterProvider>", () => {
         data: {
           key1: "value1",
         },
+        loaderData: {
+          key1: "value1",
+        },
         handle: "1",
         id: "0",
         params: {},
@@ -124,6 +127,9 @@ describe("A <StaticRouterProvider>", () => {
         data: {
           key2: "value2",
         },
+        loaderData: {
+          key2: "value2",
+        },
         handle: "2",
         id: "0-0",
         params: {},
@@ -149,6 +155,9 @@ describe("A <StaticRouterProvider>", () => {
         data: {
           key1: "value1",
         },
+        loaderData: {
+          key1: "value1",
+        },
         handle: "1",
         id: "0",
         params: {},
@@ -158,6 +167,9 @@ describe("A <StaticRouterProvider>", () => {
         data: {
           key2: "value2",
         },
+        loaderData: {
+          key2: "value2",
+        },
         handle: "2",
         id: "0-0",
         params: {},
@@ -262,6 +274,9 @@ describe("A <StaticRouterProvider>", () => {
         data: {
           key1: "value1",
         },
+        loaderData: {
+          key1: "value1",
+        },
         handle: "1",
         id: "0",
         params: {},
@@ -271,6 +286,9 @@ describe("A <StaticRouterProvider>", () => {
         data: {
           key2: "value2",
         },
+        loaderData: {
+          key2: "value2",
+        },
         handle: "2",
         id: "0-0",
         params: {},
@@ -296,6 +314,9 @@ describe("A <StaticRouterProvider>", () => {
         data: {
           key1: "value1",
         },
+        loaderData: {
+          key1: "value1",
+        },
         handle: "1",
         id: "0",
         params: {},
@@ -305,6 +326,9 @@ describe("A <StaticRouterProvider>", () => {
         data: {
           key2: "value2",
         },
+        loaderData: {
+          key2: "value2",
+        },
         handle: "2",
         id: "0-0",
         params: {},

packages/react-router/lib/dom/ssr/components.tsx

@@ -541,6 +541,7 @@ export function Meta(): React.JSX.Element {
     let match: MetaMatch = {
       id: routeId,
       data,
+      loaderData: data,
       meta: [],
       params: _match.params,
       pathname: _match.pathname,
@@ -554,6 +555,7 @@ export function Meta(): React.JSX.Element {
         typeof routeModule.meta === "function"
           ? (routeModule.meta as MetaFunction)({
               data,
+              loaderData: data,
               params,
               location,
               matches,

packages/react-router/lib/dom/ssr/routeModules.ts

@@ -130,9 +130,13 @@ export interface MetaMatch<
 > {
   id: RouteId;
   pathname: DataRouteMatch["pathname"];
+  /** @deprecated Use `MetaMatch.loaderData` instead */
   data: Loader extends LoaderFunction | ClientLoaderFunction
     ? SerializeFrom<Loader>
     : unknown;
+  loaderData: Loader extends LoaderFunction | ClientLoaderFunction
+    ? SerializeFrom<Loader>
+    : unknown;
   handle?: RouteHandle;
   params: DataRouteMatch["params"];
   meta: MetaDescriptor[];
@@ -160,11 +164,17 @@ export interface MetaArgs<
     LoaderFunction | ClientLoaderFunction | unknown
   > = Record<string, unknown>,
 > {
+  /** @deprecated Use `MetaArgs.loaderData` instead */
   data:
     | (Loader extends LoaderFunction | ClientLoaderFunction
         ? SerializeFrom<Loader>
         : unknown)
     | undefined;
+  loaderData:
+    | (Loader extends LoaderFunction | ClientLoaderFunction
+    ? SerializeFrom<Loader>
+    : unknown)
+    | undefined;
   params: Params;
   location: Location;
   matches: MetaMatches<MatchLoaders>;

packages/react-router/lib/router/utils.ts

@@ -814,8 +814,14 @@ export interface UIMatch<Data = unknown, Handle = unknown> {
    * {@link https://reactrouter.com/start/framework/routing#dynamic-segments Dynamic route params} for the matched route.
    **/
   params: AgnosticRouteMatch["params"];
-  /** The return value from the matched route's loader or clientLoader */
+  /**
+   * The return value from the matched route's loader or clientLoader
+   *
+   * @deprecated Use `UIMatch.loaderData` instead
+   */
   data: Data;
+  /** The return value from the matched route's loader or clientLoader */
+  loaderData: Data;
   /** The {@link https://reactrouter.com/start/framework/route-module#handle handle object} exported from the matched route module */
   handle: Handle;
 }
@@ -830,6 +836,7 @@ export function convertRouteMatchToUiMatch(
     pathname,
     params,
     data: loaderData[route.id],
+    loaderData: loaderData[route.id],
     handle: route.handle,
   };
 }

packages/react-router/lib/types/route-module-annotations.ts

@@ -35,7 +35,9 @@ type MetaMatch<T extends MatchInfo> = Pretty<{
   params: Record<string, string | undefined>;
   pathname: string;
   meta: MetaDescriptor[];
+  /** @deprecated Use `MetaMatch.loaderData` instead */
   data: GetLoaderData<T["module"]>;
+  loaderData: GetLoaderData<T["module"]>;
   handle?: unknown;
   error?: unknown;
 }>;
@@ -51,8 +53,14 @@ type CreateMetaArgs<T extends RouteInfo> = {
   location: Location;
   /** {@link https://reactrouter.com/start/framework/routing#dynamic-segments Dynamic route params} for the current route. */
   params: T["params"];
-  /** The return value for this route's server loader function */
+  /**
+   * The return value for this route's server loader function
+   *
+   * @deprecated Use `Route.MetaArgs.loaderData` instead
+   */
   data: T["loaderData"] | undefined;
+  /** The return value for this route's server loader function */
+  loaderData: T["loaderData"] | undefined;
   /** Thrown errors that trigger error boundaries will be passed to the meta function. This is useful for generating metadata for error pages. */
   error?: unknown;
   /** An array of the current {@link https://api.reactrouter.com/v7/interfaces/react_router.UIMatch.html route matches}, including parent route matches. */
@@ -109,7 +117,9 @@ type Match<T extends MatchInfo> = Pretty<{
   id: T["id"];
   params: Record<string, string | undefined>;
   pathname: string;
+  /** @deprecated Use `Match.loaderData` instead */
   data: GetLoaderData<T["module"]>;
+  loaderData: GetLoaderData<T["module"]>;
   handle: unknown;
 }>;