Salesforce B2C Commerce SFRA Development
Before Writing Code
Fetch live docs:
- WebFetch
github.com/SalesforceCommerceCloud/storefront-reference-architecture for SFRA source
- Web-search
site:developer.salesforce.com SFRA architecture MVC for MVC patterns
- Web-search
site:developer.salesforce.com SFRA cartridge overlay for overlay best practices
- Web-search
site:developer.salesforce.com module.superModule for extension patterns
- Web-search
site:developer.salesforce.com SFRA getting started for latest docs
Conceptual Architecture
SFRA Overview
SFRA (Storefront Reference Architecture) is the reference implementation for B2C Commerce storefronts:
- Server-side MVC -- Models, Views (ISML), Controllers
- Cartridge overlay system -- stack custom cartridges on top of base
- module.superModule -- extend base functionality without copying code
- Client-side build -- Webpack bundles JS and SCSS
- Page Designer -- visual page building with reusable components
Four Key Principles
| Principle |
Rule |
| Overlay |
Never modify app_storefront_base -- create custom cartridges that layer on top |
| Extend |
Use module.superModule to inherit and augment, not replace |
| Hooks |
Use commerce hooks for order, payment, and shipping customization |
| Services |
Use the Service Framework for external integrations (payment gateways, ERP) |
Cartridge Path Resolution
The cartridge path (configured in Business Manager) resolves files left-to-right. The leftmost cartridge wins.
Example path: app_custom:app_storefront_base
- Request for
controllers/Product.js checks app_custom first, falls back to app_storefront_base
- Templates, models, and scripts follow the same resolution
Cartridge Directory Structure
app_custom/cartridge/
├── controllers/ # Route handlers
├── models/ # Data models
├── scripts/ # Helpers, services
├── templates/ # ISML templates
├── experience/ # Page Designer
└── client/default/ # JS + SCSS source (Webpack)
module.superModule
module.superModule resolves to the next cartridge in the path that provides the same module. This is how you extend without duplicating:
- Controllers:
var base = module.superModule; server.extend(base); then use append/prepend/replace
- Models: Call base constructor with
base.call(this, apiProduct, options), then add properties
- Scripts: Import base, extend functions, re-export with spread
MVC Pattern
| Layer |
Location |
Role |
| Controller |
controllers/*.js |
Route handling via server module |
| Model |
models/**/*.js |
Transform API data to view-friendly objects |
| View |
templates/default/**/*.isml |
ISML templates for HTML rendering |
| Client JS |
client/default/js/ |
Browser-side behavior (Webpack bundled) |
| SCSS |
client/default/scss/ |
Styles (compiled to CSS) |
Extend vs Replace Controllers
| Approach |
When |
Trade-off |
server.extend(base) + append |
Adding data, logging, analytics |
Keeps base logic; auto-receives base updates |
server.replace('Route', fn) |
Fundamentally different logic |
You own the entire implementation; no base updates |
Prefer extend + append in nearly all cases. Only replace when the base logic is wrong for your use case.
Client-Side Build
SFRA uses Webpack to build client assets from client/default/js/ and client/default/scss/. Output goes to cartridge/static/default/. Client JS can extend base modules:
// Pattern: Extend base client module
var base = require('base/product/detail');
// Fetch live docs for base module API
Site Preferences and Custom Objects
- Site Preferences:
Site.getCurrent().getCustomPreferenceValue('prefName') -- store-level configuration
- Custom Objects:
CustomObjectMgr.getCustomObject('Type', 'key') -- custom data structures
- Both are managed in Business Manager and accessed via
dw.* API
Best Practices
Cartridge Overlay
- Never modify
app_storefront_base
- Name custom cartridges consistently:
app_custom_[sitename] or int_custom_[feature]
- Use
module.superModule to extend -- avoid code duplication
- Test overlays after base cartridge updates
Controllers and Models
- Use
server.extend() to inherit base routes
- Keep controllers thin -- move logic to models and scripts
- Call base model constructor, then add properties
- Always call
next() in middleware chain
Templates and Client Code
- Use
<isinclude> for reusable components
- Use resource bundles for all text:
Resource.msg('key', 'bundle', null)
- Import and extend base client JS modules
- Minimize jQuery -- prefer vanilla JS for performance
Security and Performance
- Use
Transaction.wrap() for all database writes
- Encode output in templates to prevent XSS
- Use CSRF tokens for state-changing operations
- Cache expensive operations via
CacheMgr
Fetch the SFRA GitHub repository, developer documentation, and module.superModule guide for exact patterns, API references, and best practices before implementing.
1---2name: sf-b2c-sfra3description: Build B2C Commerce storefronts with SFRA (Storefront Reference Architecture) — cartridge overlay system, MVC pattern, app_storefront_base, module.superModule inheritance, middleware chain, and site-specific customizations. Use when developing SFRA-based storefronts.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/sf-b2c-sfra7---89# Salesforce B2C Commerce SFRA Development1011## Before Writing Code1213**Fetch live docs:**141. WebFetch `github.com/SalesforceCommerceCloud/storefront-reference-architecture` for SFRA source152. Web-search `site:developer.salesforce.com SFRA architecture MVC` for MVC patterns163. Web-search `site:developer.salesforce.com SFRA cartridge overlay` for overlay best practices174. Web-search `site:developer.salesforce.com module.superModule` for extension patterns185. Web-search `site:developer.salesforce.com SFRA getting started` for latest docs1920## Conceptual Architecture2122### SFRA Overview2324SFRA (Storefront Reference Architecture) is the reference implementation for B2C Commerce storefronts:2526- **Server-side MVC** -- Models, Views (ISML), Controllers27- **Cartridge overlay system** -- stack custom cartridges on top of base28- **module.superModule** -- extend base functionality without copying code29- **Client-side build** -- Webpack bundles JS and SCSS30- **Page Designer** -- visual page building with reusable components3132### Four Key Principles3334| Principle | Rule |35|-----------|------|36| **Overlay** | Never modify `app_storefront_base` -- create custom cartridges that layer on top |37| **Extend** | Use `module.superModule` to inherit and augment, not replace |38| **Hooks** | Use commerce hooks for order, payment, and shipping customization |39| **Services** | Use the Service Framework for external integrations (payment gateways, ERP) |4041### Cartridge Path Resolution4243The cartridge path (configured in Business Manager) resolves files left-to-right. The **leftmost cartridge wins**.4445Example path: `app_custom:app_storefront_base`46- Request for `controllers/Product.js` checks `app_custom` first, falls back to `app_storefront_base`47- Templates, models, and scripts follow the same resolution4849### Cartridge Directory Structure5051```52app_custom/cartridge/53├── controllers/ # Route handlers54├── models/ # Data models55├── scripts/ # Helpers, services56├── templates/ # ISML templates57├── experience/ # Page Designer58└── client/default/ # JS + SCSS source (Webpack)59```6061### module.superModule6263`module.superModule` resolves to the next cartridge in the path that provides the same module. This is how you extend without duplicating:6465- **Controllers**: `var base = module.superModule; server.extend(base);` then use `append`/`prepend`/`replace`66- **Models**: Call base constructor with `base.call(this, apiProduct, options)`, then add properties67- **Scripts**: Import base, extend functions, re-export with spread6869### MVC Pattern7071| Layer | Location | Role |72|-------|----------|------|73| **Controller** | `controllers/*.js` | Route handling via `server` module |74| **Model** | `models/**/*.js` | Transform API data to view-friendly objects |75| **View** | `templates/default/**/*.isml` | ISML templates for HTML rendering |76| **Client JS** | `client/default/js/` | Browser-side behavior (Webpack bundled) |77| **SCSS** | `client/default/scss/` | Styles (compiled to CSS) |7879### Extend vs Replace Controllers8081| Approach | When | Trade-off |82|----------|------|-----------|83| `server.extend(base)` + `append` | Adding data, logging, analytics | Keeps base logic; auto-receives base updates |84| `server.replace('Route', fn)` | Fundamentally different logic | You own the entire implementation; no base updates |8586Prefer `extend` + `append` in nearly all cases. Only `replace` when the base logic is wrong for your use case.8788### Client-Side Build8990SFRA uses Webpack to build client assets from `client/default/js/` and `client/default/scss/`. Output goes to `cartridge/static/default/`. Client JS can extend base modules:9192```javascript93// Pattern: Extend base client module94var base = require('base/product/detail');95// Fetch live docs for base module API96```9798### Site Preferences and Custom Objects99100- **Site Preferences**: `Site.getCurrent().getCustomPreferenceValue('prefName')` -- store-level configuration101- **Custom Objects**: `CustomObjectMgr.getCustomObject('Type', 'key')` -- custom data structures102- Both are managed in Business Manager and accessed via `dw.*` API103104## Best Practices105106### Cartridge Overlay107- Never modify `app_storefront_base`108- Name custom cartridges consistently: `app_custom_[sitename]` or `int_custom_[feature]`109- Use `module.superModule` to extend -- avoid code duplication110- Test overlays after base cartridge updates111112### Controllers and Models113- Use `server.extend()` to inherit base routes114- Keep controllers thin -- move logic to models and scripts115- Call base model constructor, then add properties116- Always call `next()` in middleware chain117118### Templates and Client Code119- Use `<isinclude>` for reusable components120- Use resource bundles for all text: `Resource.msg('key', 'bundle', null)`121- Import and extend base client JS modules122- Minimize jQuery -- prefer vanilla JS for performance123124### Security and Performance125- Use `Transaction.wrap()` for all database writes126- Encode output in templates to prevent XSS127- Use CSRF tokens for state-changing operations128- Cache expensive operations via `CacheMgr`129130Fetch the SFRA GitHub repository, developer documentation, and module.superModule guide for exact patterns, API references, and best practices before implementing.