Routing

When a user makes a GET request on your storefront domain, your React app chooses one component to render in response. This type of component is called a route. All the routes available for rendering are defined in an array of objects called routes in app/routes.jsx.

The routes array follows the route configuration shape, as defined by React Router. Each object in the routes array can have the following properties:

KeyTypeDescriptionReference Docs
pathAn Express-style string, an array of strings, or a regular expressionThe path that is compared to the incoming request path for a potential matchReact Router API → <Route> → path
componentFunction (imported into routes.jsx)Component to render if the path matches the requestReact Router API → <Route> → component
exactBooleanDetermines whether the path must be an exact match or notReact Router API → <Route> → exact

A newly generated project already includes objects in the routes array for many standard ecommerce pages, such as home, PLP, and PDP.

React Router

But how does your React app choose the right component to render for any given request? We use the React Router library to search sequentially through the route configuration objects in the routes array until it finds a path string that matches the requested path.

React Router gives you lots of options for constructing your path strings. You can specify more than one path for the same component and use regular expressions to match paths that follow a pattern.

React Router is also used throughout the Retail React App to implement navigation. For example, all hyperlinks use React Router’s Link component. React Router offers other components that give you access to browser history, query parameters, and more.

To learn more about using React Router, see the official documentation. (Stick to the documentation for version 5 because other versions use a different pattern matching system.)

The routeComponent Function

Each component specified in the routes array is automatically enhanced by the routeComponent function, a higher-order component from the PWA Kit React SDK. The base class that is used to construct routeComponent defines several static methods, including two important ones that storefront developers can customize: getProps and shouldGetProps.

The getProps Method

The getProps method is used to supply data, often fetched from API requests, to routeComponent via the props object.

When routeComponent enhances a component from the routes array, it looks inside the component’s properties for a function named getProps. If you define a function there, it will be exposed as a method of the enhanced component. You don’t have to define the function for every component in the routes array, just the ones where you fetch data before rendering them.

The getProps function that you define is expected to return a promise. When the promise settles, its resolved value is passed to the enhanced component through the props object before the component is rendered.

When a component from the routes array is rendered, the component’s getProps method is supplied with a single JavaScript object. This object has the following properties, depending on the rendering context:

KeyTypeDescriptionAvailabilityMore Information
isLoadingBooleanDescribes the current execution state of the getProps function: true when executing and false when not executing.Client side only
paramsObjectContains object properties that correspond to the named route parameters in an Express-style route string. Example: If you have the route /user/:name, then the value of :name in the request path is available as params.name. Default value: {}.Both client side and server sideExpress API → Request → req.params
reqObjectA version of Node’s request object enhanced by Express. Represents the HTTP request and with properties for the query string, parameters, body, HTTP headers, and more.Server side onlyExpress API → Request
resObjectRepresents the HTTP response that an Express app sends when it gets an HTTP request.Server side onlyExpress API → Response
locationStringThe URL of the request.Both client side and server sideNot part of the Express API

Handling Errors

To handle errors in a getProps function, you have two options.

The first option is to throw an HTTPError object, which can be imported from pwa-kit-react-sdk/ssr/universal/errors. When you throw an HTTPError, a dedicated Error component is rendered.

The second option is to use props to inform the rendered component of the error so that it can be used in custom error-handling logic.

Here’s an example that uses both error-handling approaches:

Writing getProps Functions

The object returned by getProps is serialized and embedded in the rendered HTML via an object called __PRELOADED_STATE__ in the page source.

To keep the size of the rendered HTML down, be selective in what data to return in getProps. For example, avoid returning the whole response from an API request, if possible.

To preview the version of the page that is rendered on the server side in your browser, append ?mobify_server_only to the URL. This query parameter stops the hydration process so that the browser won’t take over rendering, leaving the page unchanged after server-side rendering. To see a pretty-printed version of the __PRELOADED_STATE__ object, add ?mobify_server_only&mobify_pretty to the query string.

When users navigate to subsequent pages during client-side rendering, the page is rendered immediately. Since rendering can happen while getProps is still fetching data, always write conditional code in your components to handle undefined props. Also remember to render a placeholder component (like Skeleton from Chakra UI) while props are undefined.

The shouldGetProps Method

The shouldGetProps method controls when to call the getProps method. During server-side rendering, shouldGetProps is called only one time. During client-side rendering, it’s called every time the React lifecycle method componentDidUpdate is called.

By default, getProps calls getProps every time location.pathname changes. You can override the default behavior for each component in the routes array by defining your own function called shouldGetProps as a property of the component. You can customize shouldGetProps to inspect the request and only call getProps for certain requests.

Next Steps

Get a deeper understanding of routing by reviewing source code. Here are some key files to check out in the Retail React App:

  • app/routes.jsx: demonstrates the Express-style syntax for path matching, including named route parameters.
  • app/pages/product-detail/index.jsx: this sample component for the PDP includes custom functions for both getProps and shouldGetProps.
  • app/components/_app_config/index.jsx: includes extensive configuration code and an app-wide getProps function.

As you read through the PWA Kit documentation, don’t miss the architecture guide for The Retail React App.