Routing

When a user makes a request on your storefront domain, it is handled by an Express.js handler named render that is defined in pwa-kit-react-sdk/ssr/server/react-rendering. The handler chooses a component to render in response. This type of component is called a route. The routes that are 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:

Key	Type	Description	Reference Docs
path	An Express-style string, an array of strings, or a regular expression	The path that is compared to the incoming request path for a potential match	React Router API → Route component → path
component	Function (imported into `routes.jsx`)	Component to render if the path matches the request	React Router API → Route component → component
exact	Boolean	Determines whether the path must be an exact match or not	React Router API → Route component → exact

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

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.)

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 is used to supply data 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 is exposed as a method of the enhanced component. You don’t have to define the function for every component in the routes array, only 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 when 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:

Key	Type	Description	Availability	More Information
`params`	Object	Contains 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 side	Express API → Request → req.params
`req`	Object	A 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 only	Express API → Request
`res`	Object	Represents the HTTP response that an Express app sends when it gets an HTTP request.	Server side only	Express API → Response
`location`	String	The URL of the request.	Both client side and server side	Not part of the Express API

As of v3.0.0, we introduced a new data fetching strategy called withReactQuery that you can use instead of getProps.
You can use both withReactQuery and withLegacyGetProps at the same time.
getProps and shouldGetProps were removed from the default template of pages of the Retail React App, but aren’t deprecated. Long-term support for these methods remains.

See Upgrade to v3.

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:

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 ?__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 ?__server_only&__pretty_print 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.

On the client side, your component’s render method is called before and after getProps resolves. Use the isLoading prop passed to your component to decide whether to render a loading screen or not.

When making multiple HTTP requests in getProps, try to make them in parallel. If you can’t make them in parallel, consider moving them to client-side rendering.

If you only want to fetch data on the client side, use React hooks in your component instead of getProps.

If you want to run the same code for all routes, you can define a getProps function that belongs to the App component, which is one of the special components. Special components are used to add functionality that is shared across multiple routes. To learn more about the App component and other special components, see our guide to Special Components.

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 the value of 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.

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.

For an alternative routing approach, check out URL Resolution.

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