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
The routes array follows the route configuration shape, as defined by React Router. Each object in the
routes array can have the following properties:
|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
|Function (imported into
|Component to render if the path matches the request
|React Router API → Route component → component
|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 method is used to supply data fetched from API requests, to
routeComponent via the
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.
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
|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
|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
|Represents the HTTP response that an Express app sends when it gets an HTTP request.
|Server side only
|Express API → Response
|The URL of the request.
|Both client side and server side
|Not part of the Express API
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
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.
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.
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
app/components/_app_config/index.jsx: includes extensive configuration code and an app-wide
As you read through the PWA Kit documentation, don’t miss the architecture guide for The Retail React App.