React Resource Router (RRR)

The resourceContext prop allows you to inject data into the lifecycle of your resources. This data is automatically made available to the getKey and getData functions of every resource associated with your routes. This is useful for passing API base URLs, environment flags, or authentication tokens that resources need to construct keys or fetch data.

import { environment } from './constants';

export const App = () => (
  <Router history={history} routes={routes} resourceContext={{ environment }}>
    <RouteComponent />
  </Router>
);

React Resource Router (RRR) is a configuration-driven routing solution for React. It manages single-page application (SPA) route matching, data fetching, and progressive rendering.

Key architectural concepts:

• Static Configuration: Routing is driven by a central array of route objects.
• Asynchronous Data Fetching: Data for a route is requested as early as possible (before the component renders) to improve performance and prepare for React Concurrent Mode.
• Progressive Rendering: The page renders progressively as asynchronous requests resolve.
• Server/Client Parity: It works on both client and server without requiring a full traversal of the React tree.

Router Resources are objects used by the router to fetch, cache, and provide data to route components.

When you include resources in the resources array of a route configuration object, the router manages their lifecycle:

1. Initial Load: Data is fetched as soon as the Router is mounted.
2. Route Transitions: Data is re-fetched if the existing resource data has expired.

By placing the Router high up in your React component tree, you trigger these asynchronous data requests as early as possible, which helps achieve faster meaningful render times.

To prevent circular dependencies and ensure predictable execution, you must follow these rules when defining resources:

1. Resource List: There must be a well-defined list of resources (typically the route resource list).
2. Mandatory Listing: Any resource that uses depends must be present in the resource list.
3. Precedence: A resource may only depend on resources that precede it in the resource list.
4. Self-Dependency: A resource may depend on itself; this allows its getData() function to access its own previous value.
5. Unlisted Constraints: Unlisted resources are not allowed to contain dependencies.

Error Handling: If a resource violates these rules, its getData() function will not be called, and the system will throw a error: ResourceDependencyError.

The ResourceSubscriber component allows you to subscribe to the state of a specific resource using a render prop. This is recommended only if you cannot use the useResource hook.

import { ResourceSubscriber } from 'react-resource-router';
import { avatarResource } from '../routing/resources';

export const Avatar = () => (
  <ResourceSubscriber resource={avatarResource}>
    {({ data, loading }) => {
      const image = loading ? '' : data;
      return <Circle image={image} />;
    }}
  </ResourceSubscriber>
);

To enable routing, mount the Router component at the top level of your React tree. The Router requires a RouteComponent as a child.

Required props for Router:

• routes: Your array of route configuration objects.
• history: A history object (e.g., created via createBrowserHistory).
• plugins: An array of plugins (e.g., createResourcesPlugin).

import {
  Router,
  RouteComponent,
  createBrowserHistory,
} from 'react-resource-router';
import { createResourcesPlugin } from 'react-resource-router/resources';
import { appRoutes } from './routing/routes';

const history = createBrowserHistory();
const resourcesPlugin = createResourcesPlugin({});

const App = () => (
  <Router routes={appRoutes} history={history} plugins={[resourcesPlugin]}>
    <RouteComponent />
  </Router>
);

When creating custom actions that interact with the Resource Store, you must ensure they correctly handle dependency side-effects by wrapping them appropriately.

1. Wrap Public Actions: Actions that may produce side-effects must be wrapped using actionWithDependencies() or mapActionWithDependencies(). This allows the system to generate the necessary execution tuples.
2. Implement Private Actions: The actual logic of the action should be implemented as a private action that is not wrapped. This private action is what gets dispatched during the executing state iteration.
3. Accessing Dependencies: Inside your private action, you can use:
   • executeForDependents(resource, action): To manually trigger specific actions on dependent resources.
   • getDependencies(resource): To retrieve the current data for the resource's dependencies.

You can access the current state of the router using one of three methods. It is recommended to use the useRouter hook or the RouterSubscriber component for modern implementations. The withRouter higher-order component (HoC) is available primarily to assist with migrations from react-router.

• Hook: useRouter (Recommended)
• Component: RouterSubscriber (Recommended)
• Higher-Order Component: withRouter (Legacy/Migration support)