The 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 Salesforce Commerce APIs and hosting it on the 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 Getting 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 the 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 end-to-end tests using Cypress.|
|Run end-to-end tests in continuous integration (CI) mode.|
|Run Lighthouse tests.|
|Run a bundlesize test.|
The unit tests are included alongside each of the page components in their respective directories, and the end-to-end tests are found in the
To start the unit tests, run the following command in your terminal:
To start the end-to-end tests, run the following command in your terminal while your local development server is running:
Lighthouse Performance Testing
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.
Commerce Cloud 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 customer, product, promotion, gift certificates, and search. For baskets and orders, it also uses OCAPI.
Shopper Login and API Access Service
To authorize certain API requests on behalf of shoppers, the
CommerceAPI class relies on a Commerce API called the Shopper Login and API Access Service (SLAS). By default, requests to SLAS are made through a proxy that is configured in
package.json. For this proxy configuration to work, you must use the SLAS Admin API to configure a public client for your storefront. See the SLAS Admin API guide for instructions on how to configure a public client.
Before you can configure a public client, you must complete several other steps, all of which are described in the SLAS Admin API guide. These steps include: setting up an API client for administrator use, requesting an access token, and using the access token to configure the API client via the SLAS Admin API.
When you configure the public client, you must include the callback URIs for all of your Managed Runtime environments in the
redirectUri array that you pass to the SLAS Admin API. For example, if you have an environment called
test and its
my-project-test.mobify-storefront.com, then you must include
https://my-project-test.mobify-storefront.com/callback in the
redirectUri array. The array must include the callback URIs for all your other environments too.
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
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. Salesforce plans to open-source both the PWA Kit React SDK and the entire Retail React App so that the Commerce Cloud community can contribute to their evolution.
Other Core Technologies
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.
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 tag|
|React Router||Maps URL paths to React components. Paths can be expressed as patterns that are matched from most specific to least specific.|
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