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. 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.
If you don’t have a GitHub account, seeSalesforce Commerce Cloud GitHub Repositories and Access .
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
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. Provides functionality for payment integration with Stripe.
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.mandatekey name entry in
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.
- 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. You can 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_basecartridge and a
modulescartridge that includes the server module.
- storefrontdata—Required. Contains the data for SFRA.
If you downloaded the repositories, expand the .zip files.
On macOS, you can use the command-line unzip utility to expand the files.
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.
Open a command prompt and navigate to the
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.
Use npm to install the modules included with SFRA. This approach is possible only if you're in the
storefront-reference-architecturedirectory 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:
Open a command-line terminal.
Navigate to the top-level folder of the repository containing the cartridges directory, such as
To compile only CSS:
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
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:
- Clone or download the sfra-jsdoc repository from GitHub.
- 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.
In the cartridge you want to upload, locate, or create a
dw.jsonfile is automatically created if the
createCartridgebuild tool command is used to create the cartridge. However, for some cartridges, such as the
modulescartridges provided by B2C Commerce, you must create the
dw.jsonfile and add it to the cartridge. Create the
dw.jsonfile in the top-level folder of the repository, as a sibling of the
dw.jsonfile 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.
To upload the code, use the applicable command.
To upload all cartridges for the repository, use
To upload a specific cartridge, use
uploadCartridgewith the name of the cartridge:
To upload a single file, use
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
If you use the same commands as the
watchcommand makes it simple to keep the code on your sandbox instanace up-to-date.
Make sure that your code is actually on the server:
Select Administration > Site Development > Code Deployment.
Click the Code Version link for the code version you specified in the
If your cartridge was uploaded successfully, it appears in the list of cartridges on the Version Summary page.
upload commands are wrappers for the Dwupload project. Download the project from GitHub if you want to contribute.