Retail React App
The Retail React App is a set of sample code and tooling designed to give you a head start on building your storefront on top of APIs and hosting it on Managed Runtime. This architecture guide describes the structure and contents of the Retail React App and highlights its flexible, open-source foundation.
All PWA Kit projects start with the same set of files. At the start of a project, these files are generated by running a script. (This process is described in full in the Get Started guide.)
To get an overview of how the Retail React App works, start by exploring its file structure. Here’s a listing of all the files and directories of a freshly generated project with a brief description for each one. (The technologies mentioned in the descriptions are covered in more detail later in this guide.)
To automate routine development tasks, the Retail React App includes several scripts. Use the command
npm run <SCRIPT_NAME> to run them from the terminal.
Here’s a complete list of all the included scripts with a description of each one:
|Builds the project in production mode and creates two webpack-bundle-analyzer reports. Use the reports to monitor the size of your code bundle.|
|Compile all localized messages into AST format.|
|Automatically extract the default locale’s messages from your React components.|
|Format the code using Prettier.|
|Find inconsistent code styling using ESlint.|
|Automatically fix ESlint errors.|
|Build the project in production mode.|
|Push the code bundle (production build artifacts) to Managed Runtime.|
|Save Runtime Admin credentials locally (for push command).|
|Start the SSR server.|
|Start the SSR server using the Node.js inspector.|
|Start the SSR server with a pseudo locale.|
|Run unit tests using Jest.|
|Run Lighthouse tests.|
|Run a bundlesize test.|
Your project comes with two example test suites for quality assurance: unit tests created with Jest and React Testing Library.
The unit tests are included alongside each of the page components in their respective directories.
To start the unit tests, run the following command in your terminal:
To learn more about testing your storefront, review the source code for the example test suites and explore the documentation for Jest and React Testing Library.
From the start, the Retail React App gets excellent performance scores, as measured by Google’s Lighthouse test suite. We make it easy to monitor your Lighthouse scores throughout development using the following script:
The script runs Lighthouse three times on your storefront and uploads the median scores for each category to Google. Google then uses those scores to generate a report. A link to the report is output by the script before it exits.
To use Salesforce APIs to access shopper data, an administrator must complete the tasks described in Set Up API Access.
Shopper data in the Retail React App is accessed through a class called
CommerceAPI that is built on top of the commerce-sdk-isomorphic client. You can customize the
CommerceAPI class in
app/commerce-api/index.js and configure it in
CommerceAPI class is automatically injected in each page’s
getProps method. For example, you can access the API wrapper from a page component like this:
CommerceAPI wrapper currently uses the Commerce API for products, promotions, gift certificates, and search. Each of these features are provided with their own set of endpoints, which are documented separately in the B2C Commerce API reference.
To authorize API requests on behalf of registered shoppers and guests, the CommerceAPI class relies on a Salesforce Commerce API called the Shopper Login and API Access Service (SLAS).
For baskets and orders, the CommerceAPI class also uses the Open Commerce API (OCAPI).
Instructions for setting up the Salesforce Commerce API (including SLAS) and OCAPI are covered in Set Up API Access.
The Chakra Theming system is based on the System UI Theme Specification. You can customize the look and feel of your components to suit your brand by updating the values in
Theming is available for most of the reusable components in
app/components but isn’t available for the pages like the Product Details Page or Product Listing Page. To change the styling for these pages, edit the inline styles in the source code for their respective page components in
To include custom SVG icons in the project, add them to the
app/assets/svg directory, import them in
app/components/icons/index.js, and export the React
icon component like this:
export const MyCustomIcon = icon('my-custom-icon').
The imported SVG icons are packaged into an SVG sprite at build time, and the sprite is included in the server side rendered HTML.
The PWA Kit React SDK is a library that supports the isomorphic rendering pipeline for PWA Kit storefronts. It contains many key classes, functions, and components that power the Retail React App. For example, the
render() function in
app/ssr.js that kicks off the entire rendering and routing process is imported from the SDK.
The SDK abstracts away some of the implementation details for server-side rendering, caching, and proxying while giving you plenty of opportunities to customize their operation. It also provides general-purpose utilities and tools for maintaining a single set of code that can be rendered both on the client side and the server side.
Salesforce maintains the SDK as a separate
npm package from the Retail React App so that improvements can be made more easily.
The PWA Kit React SDK and the entire Retail React App are open-source projects and available on GitHub. We welcome contributions from the Commerce Cloud community!
The open-source technologies listed in this section are the ones that are used most frequently by the Retail React App. They’re also the hardest to replace with alternatives, so we selected them not only for their performance characteristics, but also for their reputation. Each one is actively maintained, highly customizable, well documented, and widely used.
Here’s a brief overview of each of these core technologies, many of which are probably familiar to you already:
Express allows you to configure common web server settings, such as the connection port and the location of templates for returning the response. It also allows you to add additional request processing middleware at any point within the request handling pipeline.
Node.js uses a non-blocking or asynchronous architecture, which is ideal for building highly scalable and data-intensive storefronts.
React is a framework developed by Facebook to create single-page apps that deliver fast, fluid, and immersive user interfaces.
In a React app, the user interface is built with discrete components that are typically arranged in complex hierarchies. In a well-designed React app, each component is only responsible for one job—and often that job is just to contain other components.
The component hierarchy in the Retail React App is designed for extensibility. You can build on top of the included components or swap them out for new components.
Packages related to React:
|Loadable Components||Speeds up performance through code-splitting of larger bundles.|
|ReactDOM||Provides DOM-specific methods that can be used at the top level of your application.|
|ReactDOMServer||Provides the method renderToString() that pre-renders HTML on the server side.|
|React Helmet||Helps you manage changes to the document’s |
|React Router||Maps URL paths to React components. Paths can be expressed as patterns that are matched from most specific to least specific.|
Webpack consolidates your code into one or more bundles. These bundles are deployed to Managed Runtime and eventually loaded in the browser as part of the hydration process.
The Retail React App imports readymade Webpack configurations for the client side and server side form the PWA Kit React SDK. In most cases, you don’t need to change these configurations, but if you do, you can extend the Webpack configuration in
Now that you’re familiar with the structure and contents of the Retail React App, it’s time to dig deeper! Start by exploring the source code, especially the ecommerce components in