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;
 }>;