Rendering and Routing
The PWA Kit architecture builds on React’s rendering system, adding features that benefit both users and developers. This architecture guide takes a closer look at these features of PWA Kit’s rendering and routing system and how they work. Special attention is given to the parts of the PWA Kit React SDK and the Retail React App that come together to power each feature.
The following table lists each major feature of the rendering and routing system with a summary of its benefits.
|Server-side rendering||Speeds up initial page load, especially for cached requests.|
|Client-side rendering||Speeds up subsequent page load and enables a fluid user experience.|
|Request routing||Simplifies how to handle requests for pages and data by mapping request patterns to specific components.|
|Special components||Let you configure and customize your storefront across multiple pages in your React app.|
To create a favorable first impression, the first page that a user requests from your storefront must be loaded as fast as possible. But first page requests demand more rendering time than subsequent page requests. Every component on the page must be rendered, not just the ones that need updating. For the critical first page load, we use server-side rendering because it offers a powerful tool for optimizing performance: caching.
The Managed Runtime’s CDN cache can store a previously rendered version of a page and serve it to the user in an instant. There’s no faster render than one that’s already done!
To learn how to boost performance through caching, see our guide to Maximizing Your Cache Hit Ratio.
The App Server
The main code for server-side rendering is run inside the app server. The app server is an Express app that handles incoming HTTP requests and calls a function called
render in response. The app server is defined in
render function is imported from the PWA Kit React SDK. Helper functions (also from the SDK) create an instance of Express and attach the
render function to it as an Express route method for all
After the first page load, rendering duties are transferred from the server side to the client side through a process called hydration. During hydration, your React app starts running in the user’s browser. Event handlers spring into action to respond to user input. Page elements are rendered as needed and as directed by the user input in client-side rendering. This more efficient and user directed rendering enables the fluid experience that React is famous for.
The PWA Kit architecture works behind the scenes to make the transition from server-side rendering to client-side rendering as smooth as possible. For example, all your components are preloaded with all the props they need, even props that were the result of API requests. During server-side rendering, these props are serialized and embedded into the page source so that they can be used during hydration.
The following table lists some commonly used constructs that must be used with conditional code:
|Current URL from the browser||Client-side only|
|HTTP request from Express||Server-side only|
|HTTP response from Express||Server-side only|
To determine whether rendering is happening on the client side or the server side, check for the presence of the
window object. The following example uses this technique to render a price only on the client side:
Some content, such as personalized or frequently changing content, must only be rendered on the client side to get the best possible performance. See our guide to Maximizing Your Cache Hit Ratio for more information.
Now that you know how a PWA Kit storefront handles rendering, let’s consider how it knows what to render in the first place.
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
The routes array follows the route configuration shape, as defined by React Router. Each object in the
routes array can have the following properties:
|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> → path|
|component||Function (imported into ||Component to render if the path matches the request||React Router API → <Route> → component|
|exact||Boolean||Determines whether the path must be an exact match or not||React 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.
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 older 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:
The getProps Method
getProps method is used to supply data, often 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 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.
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
|Boolean||Describes the current execution state of the ||Client side only|
|Object||Contains object properties that correspond to the named route parameters in an Express-style route string. Example: If you have the route ||Both client side and server side||Express API → Request → req.params|
|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|
|Object||Represents the HTTP response that an Express app sends when it gets an HTTP request.||Server side only||Express API → Response|
|String||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/dist/ssr/universal/errors. When you throw an
HTTPError, a dedicated
Error component is rendered. (See the section on special components for more about this component.)
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
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
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.
The PWA Kit React SDK includes the following special components:
The default implementation of each special component can be overridden by your own custom version so that you can configure and customize the behavior of your storefront across multiple pages.
Let’s look at each special component separately:
The AppConfig Component
AppConfig component is positioned near the top of the component hierarchy in your React app. From this position, it allows you to insert code to configure and support app-wide features, such as state management or component theming. In the Retail React App, the
ChakraProvider component is inserted into
AppConfig to make theme values (for colors, spacing, and so on) available to all the Chakra UI components.
AppConfig component also lets you extend the set of arguments that get passed to all components that are enhanced by
routeComponent via the
getProps function. To add these arguments, define a function called
extraGetPropsArgs as a property of the
The Retail React App uses the
extraGetPropsArgs function to give all components that are enhanced by
routeComponent access to an object for interacting with the Commerce APIs:
The version of the
AppConfig component from the PWA Kit React SDK doesn’t do much—unless you override it. To override the SDK version of
AppConfig, define a file in
app/_app-config/index.jsx. A newly generated PWA Kit project already includes this file to get you started.
The App Component
App is a child of the
AppConfig component. Its main purpose is to include any components for layout and UI that persist throughout your React app, such as the header, footer, and sidebar.
App component is also enhanced by the
routeComponent function. If you define a
getProps function as a property of the
App component, it gets called when any component from the
routes array is rendered. Use it for any logic that you’d like to run on every page.
AppConfig, a default version of the
App component exists in the PWA Kit React SDK, and you’re encouraged to override it. To override the SDK version of
App, define a file in
app/_app/index.jsx. A newly generated PWA Kit project already includes this file to get you started.
Some of the features that are implemented in
App for a newly generated project include: analytics tracking, offline detection, and the
SkipNavLink component for accessibility.
The Error Component
Error component is rendered in place of the
App component under any of the following conditions:
- The user makes a request for a path that isn’t found in the
- A component from the
routesarray throws an error in its
- A component from the
routesarray throws an error during rendering.
Error component is returned, an HTTP 404 status is also included in the response header.
Like the other special components, the PWA Kit React SDK includes a default version of the
Error component, and you’re encouraged to override it. To override the SDK version of
Error, define a file in
app/_error/index.jsx. A newly generated PWA Kit project already includes this file to get you started.
By overriding the
Error component, you can do things like customize the error page for your brand, add redirects, and track the error as an analytics event.
The Document Component
Document defines the HTML that surrounds your application, such as the
Like the other special components, the PWA Kit React SDK includes a default version of the
Document component that can be overridden. But, in this case, we don’t recommend that you override it. But if you need fine-grained control over your application, you can override
Document by defining a file in
app/_document/index.jsx. A newly generated PWA Kit project does not include this file.
Rather than override the
Document component, we recommend using the React Helmet library to modify the HTML tags in
Document, such as
Get a deeper understanding of rendering and routing by reviewing source code. Here are some key files to check out in the Retail React App:
app/ssr.js: contains important app server settings, such as the default cache lifetime for pages.
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.