Upload and Configure Cartridges
Learning Objectives
After completing this unit, you’ll be able to:
- Explain which tools you can use to upload Storefront Reference Architecture (SFRA) cartridges.
- Explain the benefit of disabling page caching during development.
- List three ways to view cartridges on the server.
- Explain why you disable rule-based storefront URLs during development.
With your Storefront Reference Architecture (SFRA) cartridges built locally, the next step is to upload them to your sandbox and configure the server to recognize them. You also disable page caching and rule-based storefront URLs so you see the effect of your code changes immediately—without waiting for cached pages to expire or search engine optimization (SEO) URL rewrites to interfere with direct controller testing.
Note: Access to the SFRA repo on GitHub requires credentials for GitHub and Account Manager. The Tools & Resources for Salesforce B2C Commerce Trailhead badge and Accessing Private GitHub Repos both explain how to get access.
Upload SFRA Cartridges
Use the sgmf-scripts command-line tools to upload your cartridges. The upload commands, built into sgmf-scripts, run through npm scripts defined in your package.json.
The upload tool uses a dw.json file containing the information to establish a server connection and the code version where your cartridges upload. The sgmf-scriptscreateCartridge command creates dw.json automatically when you scaffold a new cartridge. For cartridges provided by Salesforce, such as app_storefront_base and modules, create dw.json manually. Place it in the top-level folder of the repository, as a sibling of the cartridges directory.
Here’s an example of the connection details in dw.json.
{
"hostname": "yoursandbox-inside-your-realm.demandware.net",
"username": "yourusername",
"password": "yourpwd",
"code-version": "version1"
}Push all cartridges in a repository together.
npm run uploadCartridge
Target a specific cartridge by name.
npm run uploadCartridge app_custom_mybrand
Upload a single file.
npm run upload path/to/my/filename.ext
During active development, watch detects file changes and uploads them automatically.
npm run watch
Run sgmf-scripts --help at any time to see the full list of available commands.
After the upload completes, activate your code version in Business Manager.
- In Business Manager, select App Launcher.
- Select Administration | Site Development | Code Deployment.
- Select your code version.
- Select Activate.
B2C Commerce runs the cartridges in the active code version. To switch between development states quickly, you create and manage multiple code versions in the same sandbox.
Push All Cartridges with the B2C CLI
You bundle sgmf-scripts with SFRA. For storefronts not based on SFRA or for a more modern approach you can use the B2CCLI, part of the Agentic B2C Developer Toolkit. The B2C CLI uses the same dw.json configuration sgmf-scripts uses but also supports many other ways of configuring. It’s designed for individual developers and continuous integration and deployment (CI/CD) systems.
Push All Cartridges
npx @salesforce/b2c code deploy
Watch to Detect File Changes and Upload Them Automatically
npx @salesforce/b2c code watch
Add Cartridges to the Cartridge Path
After you upload cartridges to the server, tell B2C Commerce how to stack them so they load and run in the right order. Register your cartridges in Business Manager. The order matters—cartridges at the left of the path take precedence over cartridges at the right. You register a cartridge to a site, and the same cartridge is registerable to multiple sites.
Next, load your storefront data—images, product data, and pricing—and run the storefront from Business Manager to test it. The Tools & Resources for Salesforce B2C Commerce Cloud Developers Trailhead badge covers that in detail.
To register cartridges and define the cartridge path:
- In Business Manager, select App Launcher.
- Select Administration Sites Manage Sites.
- Select your site.
- Select the Settings tab.
- In the Cartridges field, enter a colon-separated list of cartridge names. Cartridges at the left take precedence over cartridges at the right.
- Select Apply.
For a typical SFRA storefront, the cartridge path looks like this.
app_custom_mybrand:app_storefront_base:modules
Your custom cartridge is leftmost so its controllers, templates, and scripts override the cartridges in app_storefront_base. The modules folder at the right makes the server module globally available. Any LINK or plug-in cartridge goes between your custom cartridge and app_storefront_base.
Disable Page Caching
The B2C Commerce web server automatically caches HTML pages generated from ISML templates configured for caching. For example, it caches the product details page structure because it’s the same for every product. The data on that page changes per product so it isn’t cached. Caching is valuable on a live production site. During development, it works against you.
The time to live (TTL) for page data is the same as the TTL for static content on the site. When you set a TTL, you wait until the cache expires to see the effect of your code changes. If you turn off page caching in the site’s cache settings in Business Manager, every page reload fetches fresh data from the server, so each change appears immediately. Configure page caching per site—different sites in a realm can have different cache settings.
Disable Rule-Based Storefront URLs
During development, you test a new controller by typing a URL directly into the browser.
https://localhost/on/demandware.store/Sites-app-Site/default/New-Controller
Rule-based storefront URLs are automatically generated URLs designed to improve SEO and drive shoppers to the storefront. These SEO-friendly URLs rewrite the URL pattern, which conflicts with direct controller testing. The rewritten URL doesn’t match what you typed, which makes it harder to verify that individual controllers work as expected.
Here’s how to disable rule-based storefront URLs.
- In Business Manager, select App Launcher.
- Select Merchant Tools | Site Preferences | Storefront URL.
- Deselect Enable Storefront URLs.
With rule-based URLs off, you type a URL like https://localhost/on/demandware.store/Sites-RefArch-Site/default/Hello-World directly in the browser to test new controllers. Make sure that you enabled cookies in your browser.
View Cartridges on the Server
After uploading, verify that the correct code is on the server. Three ways to access cartridges on the server are available: Business Manager, a browser URL, and WebDAV.
Business Manager
- In Business Manager, select App Launcher.
- Select Administration | Manage Sites.
- Select the site that you want to view.
- Select the Settings tab.
- Open your cartridge path to confirm that the cartridges are listed correctly.
Browser URL
Access cartridges directly by using a URL in this format.
https://<hostname>/on/demandware.servlet/webdav/<organization>/cartridges/<code version ID>
WebDAV
Log in to WebDAV with your Business Manager username and password. Keep the cartridge directory name to 50 characters or fewer—that’s a WebDAV restriction. You can find the currently selected code version here.
https://<hostname>/on/demandware.servlet/webdav/<organization>/Cartridges/.version
You also use WebDAV URLs for accessing catalog and content library assets. To see the full set of WebDAV URL references:
- In Business Manager, select App Launcher.
- Select Administration | Site Development | Development Setup.
Watch for these common WebDAV problems.
- A bad server connection
- An inaccessible cartridge
Next Up
In this unit, you uploaded cartridges to the server and registered them in Business Manager. You turned off page caching and rule-based URLs so you can verify changes immediately, and you learned three ways to verify cartridges on the server.
Next, you explore how to customize cartridges.