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.

File Structure

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

Scripts

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:

NameDescription
analyze-buildBuilds the project in production mode and creates two webpack-bundle-analyzer reports. Use the reports to monitor the size of your code bundle.
compile-messagesCompile all localized messages into AST format.
extract-messagesAutomatically extract the default locale’s messages from your React components.
formatFormat the code using Prettier.
lintFind inconsistent code styling using ESlint.
lint:fixAutomatically fix ESlint errors.
prod:buildBuild the project in production mode.
pushPush the code bundle (production build artifacts) to the Managed Runtime.
save-credentialsSave Runtime Admin credentials locally (for push command).
startStart the SSR server.
start:inspectStart the SSR server using the Node.js inspector.
start:pseudolocaleStart the SSR server with a pseudo locale.
testRun unit tests using Jest.
test:e2eRun end-to-end tests using Cypress.
test:e2e-ciRun end-to-end tests in continuous integration (CI) mode.
test:lighthouseRun Lighthouse tests.
test:max-file-sizeRun a bundlesize test.

Test Suites

Quality Assurance

Your project comes with two example test suites for quality assurance: unit tests created with Jest and React Testing Library and end-to-end tests created with Cypress.

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 app/cypress directory.

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:

To learn more about testing your storefront, review the source code for the example test suites and explore the documentation for Jest, React Testing Library, and Cypress.

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 APIs

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 app/commerce-api.config.js.

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

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

Chakra UI

The Chakra UI component library is a new, yet production-ready technology that we’re excited to use in the Retail React App. It includes 50+ user interface components, all with excellent accessibility and usability. Components can be customized with style props or using JavaScript objects for more advanced styling (CSS-in-JS). All Chakra components come with well-designed base styles that can be overridden with a theming system.

Theming

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 app/theme directory.

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 app/pages.

SVG Icons

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:

Babel

Babel compiles your JavaScript code to make it compatible with a wide range of browsers and Node.js environments. It transforms advanced language syntax and polyfills any features that are missing from the environment.

Express.js

Express is a popular open-source web server framework, written in JavaScript, and run within the Node.js runtime environment. It handles HTTP requests for the routes you define as the entry points for your storefront.

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

All of the server-side code for a PWA Kit application is run on top of Node.js, an open-source runtime environment for JavaScript. The runtime environment omits browser-specific JavaScript APIs and includes its own APIs to access features of the host operating system (such as the file system) in a cross-platform way.

Node.js uses a non-blocking or asynchronous architecture, which is ideal for building highly scalable and data-intensive storefronts.

React

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.

NameDescription
Loadable ComponentsSpeeds up performance through code-splitting of larger bundles.
ReactDOMProvides DOM-specific methods that can be used at the top level of your application.
ReactDOMServerProvides the method renderToString() that pre-renders HTML on the server side.
React HelmetHelps you manage changes to the document’s tag
React RouterMaps URL paths to React components. Paths can be expressed as patterns that are matched from most specific to least specific.

Webpack

Webpack consolidates your code into one or more bundles. These bundles are deployed to the 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 webpack.config.js.

Next Steps

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 app/pages.