Get Started with SFRA

To use SFRA to develop your own storefront, first get the code and supporting tools. Then build and configure SFRA.

You must have access to the Salesforce CommerceCloud repositories on GitHub, where you are able to either download a copy of the SFRA repositories or clone the repositories on your local system. If you clone the repositories, issue git commands to perform tasks like getting the latest updates or seeing recent changes.

1. If you don’t have a GitHub account, see Salesforce Commerce Cloud GitHub Repositories and Access.

2. Search for the following repositories, and click Clone or download to copy each repository to your local system.

   Clone or download the repositories next to each other, as siblings, as in the following example. If you nest the repositories, you can’t use the build tools.

   1your project
   2├── eslint-plugin-sitegenesis
   3├── lib_productlist
   4├── plugin-applepay
   5├── plugin_commercepayments
   6├── plugin_datadownload
   7├── plugin_giftregistry
   8├── plugin_instorepickup
   9├── plugin_productcompare
   10├── plugin_salesforcepayments
   11├── plugin_sitemap
   12├── plugin_wishlists
   13├── sfra-jsdoc
   14├── sgmf-scripts
   15├── storefront-reference-architecture
   16    ├── cartridges
   17    │   ├── app_storefront_base
   18    │   └── modules
   19└── storefrontdata
   20├── app_custom_domain_mysite1
   21├── app_custom_domain_mysite2

   Note

   • eslint-plugin-sitegenesis—Optional. Used to lint and test code.

   • lib_productlist—Optional. A shared code base required by both the plugin_wishlist and plugin_giftregistry repositories.

   • plugin-applepay—Optional. Extends the base cartridge to add Apple Pay to your site.

   • plugin_commercepayments—Optional. This repository will be retired in a future version. We recommend using the plugin_salesforcepayments repository for payment integration with Stripe.

   • plugin_salesforcepayments—Optional. Provides functionality for payment integration with Adyen, Stripe, and PayPal.

     Note

   For the Stripe’s terms of service with the SEPA payment option, you must replace [the seller] with the the appropriate name in the sepa_debit.message.mandate key name entry in plugin_commercepayments/cartridges/plugin_commercepayments/cartridge/templates/resources/salesforcepayments.properties.

   See SDD Core Mandate Translations for details on the SEPA Direct Debit (SDD) payment mandate.

   :::

   The plugin_salesforcepayments and plugin_commercepayments cartridges don’t support payments that use the plugin-applepay or plugin_instorepickup cartridges. If you’re applying additional cartridges to the storefront, you must disable the plugin-applepay and plugin_instorepickup in the site preferences and in the cartridge path.

   Internet Explorer isn’t a supported browser for Salesforce Payments or Commerce Payments.

   Note

   • plugin_datadownload—Optional. Provides GDPR related functionality.
   • plugin_giftregistry—Optional. Provides gift registry functionality.
   • plugin_instorepickup—Optional. Provides buy-online-pick-up-in-store functionality.
   • plugin_productcompare—Optional. Provides functionality to compare various products.
   • plugin_sitemap—Optional. Provides sitemap functionality.
   • plugin_wishlists—Optional. Provides wishlist functionality.
   • plugin_ordermanagement-Optional. Provides Salesforce Order Management self-service functionality.
   • sfra-jsdoc—Optional. Builds the JSDoc for the project. Extend the JSDoc to include the JSDoc for custom cartridges.
   • sgmf-scripts—Required. The command-line tools that compile the project and upload the cartridges.
   • storefront-reference-architecture—Required. Includes the app_storefront_base cartridge and a modules cartridge that includes the server module.
   • storefrontdata—Required. Contains the data for SFRA.

3. If you downloaded the repositories, expand the .zip files.

   On macOS, you can use the command-line unzip utility to expand the files.

   Note

Configure the app_storefront_base cartridge and any plugin cartridges you want for your storefront.

Contribute to the dwdebugger repository, which uses the Script Debugger API to provide debugging capabilities for VSC and node-inspector.

If you want to upload your code automatically, use the upload tool included with the sgmf-scripts command-line tools.

SFRA depends on modules managed by npm. If you downloaded the repository as a .zip file, these instructions assume that you have expanded it.

1. Open a command prompt and navigate to the storefront-reference-architecture directory.

2. Download and install Node.js version 18 (which has been tested with SFRA). Test whether node is installed by entering:

   1node -v

   If node is already installed, this command returns a version number. If it’s installed, skip to the next step.

   B2C Commerce uses Node.js only for npm dependency management.

   Note

3. Use npm to install the modules included with SFRA. This approach is possible only if you’re in the storefront-reference-architecture directory and you installed Node.js.

   1npm install

   Run this command any time you download a new version of SFRA, because the dependencies included with the application sometimes change.

   Important

While packages are easy to install globally on most operating systems, it can be complicated to globally install packages on the Mac OS/X. If you’re working on a *nix or Window system, we recommend that you install the command-line build tools for SFRA globally. This approach makes it simple to create custom cartridges with the correct structure anywhere on your development machine.

1npm install -g sgmf-scripts

After installation, use the sgmf-scripts command-line tools in any directory on your machine with a syntax similar to:

1sgmf-scripts --help

If you’re installing on a Mac and get an EACCES error, try Fixing Your Permissions to globally install the node. Adjust your node installation if necessary. This process can be time-consuming. Global installation isn’t necessary, but it eliminates the installation step for any new cartridge.

If you want to install sgmf-scripts locally, enter:

1npm install sgmf-scripts

After installation, use sgmf-scripts in the current folder with a syntax similar to:

1node node_modules/sgmf-scripts --help

Build SFRA and upload code to your sandbox. If a cartridge has style sheets or JavaScript, compile it before uploading.

To compile the style sheets and JavaScript for a cartridge:

1. Open a command-line terminal.

2. Navigate to the top-level folder of the repository containing the cartridges directory, such as storefront-reference-architecture.

3. To compile both CSS and JavaScript, enter:

   1npm run compile:js && npm run compile:scss && npm run compile:fonts

   To compile only CSS:

   1npm run compile:scss

   To compile only JavaScript:

   1npm run compile:js

   Usually, you only have to compile fonts once.

   Note

The build commands are defined in the scripts section of the package.json for your top-level folder. Change the commands and add commands for other command-line tools in the package.json file.

If you have installed the sgmf-scripts node globally, use this command to see all current build commands:

1sgmf-scripts --help

If you have installed the sgmf-scripts node locally, use this command to see all current build commands:

1node node_modules/sgmf-scripts --help

Customize the build commands or add new ones in your package.json. See npm documentation for more information about adding scripts for npm.

To build an HTML version of the JSDoc:

1. Clone or download the sfra-jsdoc repository from GitHub.
2. Read the ReadMe for the most up-to-date instructions on how to configure and run the repository.

Use the SFRA command-line upload tool to upload your code.

1. In the cartridge you want to upload, locate, or create a dw.json file.

   The dw.json file is automatically created if the sgmf-scripts createCartridge build tool command is used to create the cartridge. However, for some cartridges, such as the app_storefront_base and modules cartridges provided by B2C Commerce, you must create the dw.json file and add it to the cartridge. Create the dw.json file in the top-level folder of the repository, as a sibling of the cartridges directory.

   The dw.json file contains the information required to establish a server connection and the code version to upload your cartridges to.

   1{
   2    "hostname": "yoursandbox-inside-your-realm.demandware.net",
   3    "username": "yourusername",
   4    "password": "yourpwd",
   5    "code-version": "version1"
   6}

   This file is normally unencrypted. However, because it contains the instance and password data necessary to upload code, you can use extra measures to secure it.

   Note

2. To upload the code, use the applicable command.

   • To upload all cartridges for the repository, use uploadCartridge:

     1npm run uploadCartridge

   • To upload a specific cartridge, use uploadCartridge with the name of the cartridge:

     1npm run uploadCartridge *mycartridge*

   • To upload a single file, use upload.

     If you use the same commands as the app_storefront_base cartridge, run:

     1npm run upload *path/to/my/filename.ext*

   • To detect changes to files in your cartridge and automatically upload them to the server, use watch.

     If you use the same commands as the app_storefront_base cartridge, run:

     1npm run watch

     The watch command makes it simple to keep the code on your sandbox instanace up-to-date.

3. Make sure that your code is actually on the server:

   1. Select Administration > Site Development > Code Deployment.

   2. Click the Code Version link for the code version you specified in the dw.json file.

      If your cartridge was uploaded successfully, it appears in the list of cartridges on the Version Summary page.

The command-line watch and upload commands are wrappers for the Dwupload project. Download the project from GitHub if you want to contribute.

j

Announcements

Choose Your B2C Commerce Storefront Type

B2C Commerce

SCAPI

Storefront Next

Composable Storefront

Storefront Reference Architecture (SFRA)

Frequently Asked Questions

SFRA Feature List

Learn More

Commerce Community Suite

SFRA Features and Components

SFRA Versions and Releases

Build SFRA

Configure SFRA

Customize SFRA

Troubleshoot SFRA

Contribute To SFRA

Commerce Apps ISV Developer Guide

B2C Commerce Solutions

B2C Commerce Release Notes

B2C Commerce Reference Information

Ask the Community