Get Started with SFRA

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

Only existing customers can access some of the links on this page. Visit Salesforce Commerce Cloud GitHub Repositories and Access for information about how to get access to the Commerce Cloud repositories.

You must have access to the Salesforce CommerceCloud repositories on GitHub. You can then either download a copy of the SFRA repositories or clone the repositories on your local system. If you clone the repositories, you can 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.

    your project
    ├── eslint-plugin-sitegenesis
    ├── lib_productlist
    ├── plugin-applepay
    ├── plugin_commercepayments
    ├── plugin_datadownload
    ├── plugin_giftregistry
    ├── plugin_instorepickup
    ├── plugin_productcompare
    ├── plugin_sitemap
    ├── plugin_wishlists
    ├── sfra-jsdoc
    ├── sgmf-scripts
    ├── storefront-reference-architecture
        ├── cartridges
        │   ├── app_storefront_base
        │   └── modules
    └── storefrontdata
    ├── app_custom_domain_mysite1
    ├── app_custom_domain_mysite2
    
    

    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_commercepayments cartridge doesn'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 Commerce Payments.

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

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

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

You can 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 12.21.0 (which has been tested with SFRA). You can test whether node is installed by entering:

    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.

  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.

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

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.

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

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:

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

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:

    To compile only CSS:

    To compile only JavaScript:

    Usually, you only have to compile fonts once.

The build commands are defined in the scripts section of the package.json for your top-level folder. You can 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:

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

You can 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.

You can 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.

    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.

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

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

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

    • To upload a single file, use upload.

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

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

      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.