Explore Reference Architecture Cartridges

Learning Objectives

After completing this unit, you’ll be able to:

• List what’s typically in a Storefront Reference Architecture (SFRA) cartridge stack.
  
• Explain why it’s important to keep the SFRA base cartridges edit-free.
  
• Classify the types of files in each base cartridge.
  
• List what’s typically in the cartridges folder.
  

Now that you have a general understanding of how cartridges work, let’s examine Storefront Reference Architecture (SFRA) cartridges in depth. Their contents change as Salesforce updates the software over time, so treat this information as a snapshot rather than a permanent reference. Use the official GitHub repositories for the latest content.

Explore SFRA Cartridges

A fully developed SFRA cartridge stack typically includes the base cartridge, overlay plug-ins, and one or more custom cartridges. Each layer serves a specific purpose in the stack.

Get to Know the Base Cartridges

Two items make up the SFRA base.

• app_storefront_base
• modules

These cartridges contain functionality common to most storefronts. When you leave them unedited, your code works reliably from one major B2C Commerce release to the next. You adopt new features faster and maintain a clear separation between base and custom code—which makes troubleshooting and bug-fix adoption quicker.

Note: Salesforce releases B2C Commerce multiple times per year, with both major and incremental releases.

Rather than changing the base files, layer functionality over them with plug-in and custom code cartridges. Your custom cartridges override parts of the stack with storefront branding and custom functionality. Understanding the structure of base cartridges helps you plan the other layers in your stack.

Explore the app_storefront_base Cartridge

SFRA uses a variant of model—view—controller (MVC) architecture, divided into three interconnected parts.

• Controller: Handles incoming requests, creates ViewModels, and renders pages.
  
• ViewModel: Requests data from B2C Commerce, converts B2C Commerce script API objects into pure JSON objects, and applies business logic.
  
• View: Shows the resulting data on the storefront as ISML templates.
  

The app_storefront_base cartridge contains the foundational B2C Commerce code. Multiple ViewModels use the B2C Commerce script API to retrieve data from the platform for specific functional areas, such as orders, products, and search. Each ViewModel constructs a JSON object that you use to render a template.

B2C Commerce templates define how data transforms into dynamic, HTML-based web pages shown in the browser. To write templates, you use Internet Store Markup Language (ISML), a B2C Commerce extension to HTML.

Here’s what the app_storefront_base cartridge looks like in the file system.

Within the cartridge folder, some subfolders are localizable. The client folder contains a default folder and language-specific folders. The forms, templates, and static folders follow a similar structure.

app_storefront_base
├── client        // client-side JavaScript and CSS
│   ├── js
│   └── scss
├── controllers   // business logic for the application
├── forms
├── models        // retrieves data from the server and provides it as JSON objects
├── scripts       // reusable functionality
│   ├── cart
│   ├── factories
│   ├── helpers
│   ├── payment
│   └── search
├── static        // static resources unlikely to change, such as branding images
└── templates     // ISML templates
    ├── default
    └── resources

The ViewModels in this cartridge and the objects provided by the server module are backward-compatible between major point releases. That guarantee means that you adopt new features without reworking and maintaining a clear boundary between base and custom code. Editing the app_storefront_base cartridge or server module voids the backward compatibility guarantee and complicates feature and fix adoption. Use B2C Commerce script methods to extend base cartridge functionality instead.

The backward compatibility guarantee is the main reason to keep your custom code in a separate overlay cartridge. When Salesforce releases a new version of app_storefront_base, the ViewModel structure and the server module’s JSON object properties stay consistent. Your custom cartridge, which sits to the left of app_storefront_base on the cartridge path, picks up any changes in the next release without manual merging.

Manage the Modules Folder

The modules folder sits at the same level as the cartridges directory—it’s a peer, not a subfolder of the cartridge structure. It’s as important to the SFRA project as the two cartridge folders.

The key item in modules is the server module. This module provides routing functionality for every SFRA controller. It delivers objects containing data from HTTP requests, responses, and session objects. It registers routes that map a URL to code that B2C Commerce runs when it detects that URL. The approach is conceptually similar to Node.js’s Express framework.

Any module placed in the modules folder is globally available. You require it without specifying a path in any controller or script.

var server = require('server');

The modules folder doesn’t follow a typical cartridge structure, but you upload it to the server alongside the cartridges. Don’t modify the server module directly, editing it voids backward compatibility guarantees. To extend server module functionality, create your own module in the modules folder and require the server functions from there.

Scripts placed in the modules folder are globally accessible across the entire cartridge stack. With this placement, you can require them from any controller or script without specifying a file path. This contrasts with scripts located within a cartridge’s scripts subfolder, which require a cartridge-relative path. The modules folder is the ideal location for shared utility code that must be available projectwide.

Review the Salesforce B2C Commerce for Developers Trailhead badge to understand how controllers, ViewModels, templates, and scripts work together in a complete request—response cycle.

Next Up

You explored the SFRA cartridges and learned how they’re structured. Next, you upload these cartridges to the server.

Resources

• Trailhead: Salesforce B2C Commerce for Developers
• Trailhead: Tools & Resources for Salesforce B2C Commerce Cloud Developers
• OpenJS Foundation: NodeJS: Express
• Wiki: CommonJS