Special Components

This guide assumes that you’re familiar with how routing works in a PWA Kit storefront. To learn more, see our guide to Routing.

The PWA Kit React SDK includes the following special components: AppConfig, App, Error, and Document.

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

The 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 AppConfig component.

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 Salesforce Commerce API:

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/components/_app-config/index.jsx. A newly generated PWA Kit project already includes this file to get you started.

The App component 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.

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

Like 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/components/_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 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 routes array.
  • A component from the routes array throws an error in its getProps function.
  • A component from the routes array throws an error during rendering.

When the 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/components/_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 defines the HTML that surrounds your application, such as the <html>, <head>, and <body> tags.

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/components/_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 <head>.