Get Started

Explore the Sample App

Not a Salesforce B2C Commerce customer yet? We encourage you to review the API libraries on this site. You can also check out the code and directions for building our sample app in the GitHub repository.

The sample app demonstrates how to build amazing commerce experiences with the latest commerce platform technologies. The sample app isn’t a replacement for, and doesn’t have full feature parity with, our out-of-the box fully functional storefront reference application, the B2C Commerce Storefront Reference Architecture (SFRA). But the sample app can help you get started with understanding and adopting the new commerce API. For more information, see the Sample Application FAQ.

Build and Deploy the Sample App

If you’re already a B2C Commerce customer, you can build and deploy our sample app using these steps. The sections below have more details about each step.

  1. Prepare the platform: Prepare a B2C Commerce sandbox.
  2. Configure access: Create a client ID.
  3. Create the app: Use the create-commerce-app tool to build the app.

Prerequisites

Before you begin, you’ll need a few tools and accounts configured.

  • Node.js environment: Make sure you have Node.js 12 installed, with at least npm (Node Package Manager) 5.2+. You also need 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.
  • Yarn: You’ll need the yarn package manager.
  • Git: To complete some of the steps in this procedure, you’ll need to have the Git version control system installed.
  • B2C Commerce account: To access the platform, you’ll need an Account Manager account. Check with your administrator if you don’t have an account.
  • B2C Commerce sandbox: On Demand Developer Sandboxes are a perfect fit since you can manage them with CI/CD tools similar to what you use to manage your headless apps.

Prepare the Platform

Make sure there’s data in your storefront so that you can see the features of the sample app once you’ve got it running. If you’re starting with a blank sandbox, you can install sample data. See Use Site Import/Export to Import Reference Application Demo Sites for details.

Configure Access

Log into Account Manager and create a client ID. We use standard OAuth scopes to set permissions. For information about how to configure the client ID, see Client Permissions for API Endpoints.

Create the App

  1. Download the git repo: npx create-commerce-app yourappname

  2. Change into your app folder: cd yourappname

  3. Copy the packages/storefront-lwc/app/api.example.js file, save it as packages/storefront-lwc/app/api.js, and make sure api.js is added to your .gitignore file.

  4. In api.js, provide values for the following variables. For information about how to get the appropriate values, see Commerce API Configuration Values.

    • COMMERCE_CLIENT_API_SITE_ID: Unique site ID (for example, RefArch or SiteGenesis).

    • COMMERCE_CLIENT_CLIENT_ID: Unique ID used exclusively for API access. See Add a Client API for more information.

    • COMMERCE_CLIENT_REALM_ID: Unique four-character ID (for example, bblx).

    • COMMERCE_CLIENT_INSTANCE_ID: Unique instance ID within a realm (for example, 015).

    • COMMERCE_CLIENT_SHORT_CODE: Unique region-specific merchant identifier (for example, staging-001).

    • COMMERCE_SESSION_SECRET: Unique ID for session management (for example, thisisasecretkey).

    • COMMERCE_CORS: Optionally enable CORS for GraphQL on the defined domains (for example, enable all domains with *).

      Note: If the COMMERCE_SESSION_SECRET key is not unique per customer application, session information can be unintentionally shared between ecommerce sites.

  5. Install dependencies: yarn.

  6. Build the sample application: yarn build.

  7. Start the sample application: yarn start:dev (development mode) or yarn start (production mode).

  8. Access the sample application: open your browser to http://localhost:3000.

  9. (Optional). Test the sample app: yarn test.