--- schema_version: "1" id: 01b2d1c77fcd541ff8a5c1af30fb9e6592e135af9a356dd00a67f7beb7040093 title: Routing collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/routing.md canonical_url: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/routing.html source_site: developer.salesforce.com content_type: documentation content_hash: e46803df92c041fca18d96fad7b68cf79e7933682ea49ce02951cef709e596e4 products: - Composable Storefront - Salesforce APIs --- # 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](https://www.npmjs.com/package/react-router-config/v/5.1.0#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](https://v5.reactrouter.com/core/api/Route/component) | | component | Function (imported into `routes.jsx`) | Component to render if the path matches the request | [React Router API → Route component → component](https://v5.reactrouter.com/core/api/Route/component) | | exact | Boolean | Determines whether the path must be an exact match or not | [React Router API → Route component → exact](https://v5.reactrouter.com/core/api/Route/exact-bool) | 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](https://v5.reactrouter.com/web/guides/quick-start) 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](https://v5.reactrouter.com/web/guides/quick-start). (Stick to the documentation for version 5 because other versions use a different pattern matching system.) ## routeComponent Each component specified in the `routes` array is automatically enhanced by the `routeComponent` function, a [higher-order component](https://reactjs.org/docs/higher-order-components.html) 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`. ### getProps 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://expressjs.com/en/4x/api.html#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](https://expressjs.com/en/4x/api.html#req) | | `res` | Object | Represents the HTTP response that an Express app sends when it gets an HTTP request. | Server side only | [Express API → Response](https://expressjs.com/en/4x/api.html#res) | | `location` | String | The URL of the request. | Both client side and server side | Not part of the Express API | **note:** - 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](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/upgrade-to-v3.md). ### 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: ```javascript const ProductDetails = ({name, errorProductNotFound}) => (

{errorProductNotFound ? 'Product Not Found' : name}

) ProductDetails.getProps = async ({res}) => { const response = await fetch(`https://httpbin.org/status/404`) if (!response.ok) { if (response.status !== 404) { throw new HTTPError(response.status, response.statusText) } res && res.status(404) return {errorProductNotFound: true} } const data = await response.json() return data } ``` ### 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 `?__server_only` to the URL. This query parameter stops the [hydration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/%3Chttps://en.wikipedia.org/wiki/Hydration_(web_development)>) 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](https://www.chakra-ui.com/docs/components/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](https://reactjs.org/docs/hooks-overview.html) 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](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/special-components.md#app) and other special components, see our guide to [Special Components](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/special-components.md). ### shouldGetProps 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. ## 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. For an alternative routing approach, check out [URL Resolution](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-resolution.html). As you read through the PWA Kit documentation, don’t miss the architecture guide for [The Retail React App](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/retail-react-app.md).