Explore the Sample App

Learning Objectives

After completing this unit, you’ll be able to:

  • List three components you need to install before using the Salesforce B2C Commerce sample app.
  • Explain the purpose of the B2C Commerce sample app.
  • Explain the sample app’s monorepo design.
  • Describe the sample app’s architecture.

Developer Tools

Cloud Kicks Corporation specializes in high-end custom sneakers. Vijay Lahiri, one of its senior developers, is ready to move his Salesforce B2C Commerce storefront applications toward a headless implementation. He reviewed architectural and component possibilities in the Headless Commerce Basics module, and wants to take a closer look at how developer tools like the B2C Commerce sample app can help speed headless application development.

 

Vijay Lahiri, Cloud Kicks developer

Vijay can hardly wait to get started. He takes a quick look at the API libraries available on the Commerce Cloud Developer Center, which includes API documentation, getting started guides, community forums, and more. He reviews the code and directions for building a sample app in the GitHub repository.

The Sample App

The B2C Commerce sample app is intended to provide guidance and understanding about how to get started with B2C Commerce and, what’s more… to accelerate Vijay’s adoption of headless commerce and the Salesforce Commerce Platform APIs. The sample app shows him how to build amazing ecommerce experiences using the latest B2C Commerce platform technologies.

The sample app is a headless application that uses the commerce node.js SDK to interact with the B2C Commerce Platform’s APIs. While the sample app uses recommended approaches for building a storefront, it’s not as complete or fully functional as the Commerce Cloud Storefront Reference Architecture ( SFRA).

The B2C Commerce sample app is a monorepo with a sample application and backend-for-frontend (BFF) dependency modules. What’s a monorepo? In version control systems, it’s a software development strategy where you store code for many projects in the same repository. With monorepo, you typically publish dependency modules to a (separate) public npm (Node Package Manager) server, and keep the modules you need to develop an application within a single repository.

The sample app includes different components that Vijay can use to create different shopper experiences. The sample app includes these components.

Component
Functional Description
Home Page

An interactive component that fetches and displays info such as banners and Shop and Popular categories that enables shoppers to navigate to specific products or categories.
Product Detail

An interactive component that fetches and displays product details such as product name, description, images, pricing, and promotions. A shopper can select a variation and add the product to the shopping basket.
Product Search Results
An interactive component that fetches and displays results from a search request. The results can include
info such as the product image, name, price, or color swatch images. This component lets the shopper load the product detail page from the individual product tile.
Basket
An interactive component that fetches and displays the current shopper's basket. To fetch the basket, the component issues a getBasket request. The getBasket request can return an empty basket page or a basket page that includes info such as product images, names, variation attributes, product line item unit prices, product line item total prices, availability, shipping methods, coupons, and basket totals.

Vijay starts by installing the prerequisites and reviewing the sample app’s architecture.

Check Prerequisites

Before he begins, he needs to install or access certain tools and configure a few accounts. Here’s what he does.

  1. Install Node.js 12with at least npm 5.2+.
    • Get the npx tool, which is a package runner that installs with npm 5.2+.
    • For best results, use a node version manager such as NVM to manage Node.js versions.
  2. Get the yarn package manager. Yarn lets you use and share code with other developers. It does this quickly, securely, and reliably so you don’t ever have to worry. Yarn shares code through something called a package. A package contains all the code you want to share as well as a package.json file (called a manifest) that describes the package.
  3. If you have a file permission issue on a Mac, run this first: sudo chown -R $USER /usr/local/lib/node_modules
  4. Install the Git version control system.
  5. Get an Account Manager account (login required) to access the B2C Commerce platform. Check with your admin if you don’t have one.
  6. Take a look at the Tools & Resources for Salesforce B2C Commerce Developers Trailhead module for access instructions.
  7. Get an on-demand sandbox (learn how in the Salesforce B2C Commerce On-Demand Sandbox module). You can manage it with CI/CD tools similar to what you use to manage your headless apps. 

Vijay is comfortable with these tools because he’s used them on other projects.

Architecture

The B2C Commerce sample app showcases the capabilities and best practices of building an ecommerce application on top of the Salesforce Commerce API.

  • The front end is built with Lightning Web Components (LWC).
  • The back end is built on the Salesforce Commerce API, a RESTful headless API.
  • In between, it uses GraphQL and the Salesforce Commerce Node.js SDK.

The Sample App consists of Lightning Web Components at the front-end, GraphQL and the Salesforce Commerce Node.js SDK in the middle, and the Salesforce Commerce API at the back end.

Vijay takes a closer look at these components.

Component
Description
Lightning Web Components
A Salesforce framework for building user experiences in modern JavaScript and native web components: It uses the latest web standards, and it allows you to build components once and reuse them with other frameworks.
GraphQL
An API query language that provides validation and type checking, and minimizes the data transfer between the BFF and client: The sample app comes with the interactive API explorer GraphQL Playground. Access the GraphQL Playground by booting the sample app and navigating to http://localhost:3000/api.
Apollo
A popular open source technology for GraphQL: The sample app relies on Apollo for both the client and server side implementation of GraphQL.
Salesforce Commerce NodeJS SDK
A Salesforce-provided npm package that wraps the Salesforce Commerce API and exposes a TypeScript-based interface: The library supports autocomplete features within your IDE, allowing you to view available methods, parameters, and class definitions inline in the code. The SDK is promised-based, which makes writing async functions for complex operations easy.
Salesforce Commerce API
A headless RESTful API: This API provides access to the B2C Commerce platform’s resources and process.

Project and Package Structure

The sample app groups managed packages into these categories.

  • @sfcc-core: Core modules for the BFF, including a service and extension registry and a logging abstraction.
  • @sfcc-bff: Data source implementation for the Salesforce Commerce API. It includes the GraphQL models and query and mutation resolvers. If you add a new data source to another API, you need to create another package grouping that’s similar to @sfcc-bff. Don’t mix data sources within the same package of GraphQL models and resolvers.
  • Storefront-lwc: Front-end application, built with lwc-services.

Session Management

When the client loads the sample app, the client:

  • Initializes the sample app with the express authentication middleware, passportjs. Invokes passport.session to generate a session.
  • Generates a cookie using express-session to represent the session.

Passport is authentication middleware for Node.js. You can drop it into any Express-based web application.

The sample app uses GraphQLLocalStrategy from the graphql-passport package for its authentication strategy. Authentication enables shoppers to do things like create a basket. After successful authentication, the client stores the anonymous user ID in the session corresponding to the generated cookie.

Customize and Extend Guidelines

When customizing or extending the sample app, don’t modify the packages within @sfcc-bff and @sfcc-core. These packages are published and consumed via npm. Instead, create a new custom package within the monorepo that registers itself with @sfcc-core and provides access to data from a third-party service.

Create a new custom package within the monorepo that registers itself with @sfcc-core and provides access to data from a third-party service.

The core-graphql module within @sfcc-core does a lot of the heavy lifting. Here’s what it does.

  1. Gets the registered API modules
  2. Loops over them
  3. Aggregates schemas and resolvers
  4. Starts the Apollo Server with which the Apollo Client communicates

When Vijay creates a new BFF API module, he registers it with core, creates the schema and resolvers he needs, and exposes them to the core-graphql module for aggregation through factory functions in the core-graphql module.

What’s Not Included

Not everything Vijay needs for a full, production-ready shopper experience is included in the sample app. Beyond the features of the application he builds, he needs to account for other considerations before deploying the application to production. Take a look at the Headless Implementation Guide for examples.

Next Steps

You learned what the B2C Commerce sample app is intended for and the prerequisites you need to install and configure in order to use it. You also learned about its monorepo design and three-part architecture. Next, you learn how to prepare the platform and configure access so you can create your app.

Resources