sf-b2c-cartridges

Build B2C Commerce cartridges following Salesforce Commerce Cloud architecture patterns.

Before Writing Code

Fetch live documentation FIRST:

1. Web-search for:

   • "Salesforce B2C Commerce SFRA cartridge structure 2026"
   • "SFCC cartridge naming conventions best practices"
   • "Salesforce Commerce Cloud cartridge overlay documentation"

2. Web-fetch official sources:

   • https://github.com/SalesforceCommerceCloud/storefront-reference-architecture (SFRA GitHub repo)
   • Salesforce B2C Commerce cartridge development documentation
   • SFCC LINK marketplace certification requirements

3. Verify before coding:

   • Current SFRA version and directory structure
   • Cartridge naming prefix standards
   • Required metadata fields in cartridge.properties
   • Build tool configuration (sgmf-scripts, webpack)

Conceptual Architecture

Cartridge Directory Structure

app_custom_mysite/
├── cartridge/
│   ├── controllers/    # Route handlers
│   ├── models/         # Business logic
│   ├── scripts/        # Helpers, middleware
│   ├── templates/      # ISML + i18n resources
│   └── static/         # Compiled CSS/JS/images
└── cartridge.properties

Key Directories Explained

Cartridge Naming Conventions

Cartridge Path and Overlay System

The cartridge path defines file resolution order (configured in Business Manager > Site Settings):

app_custom_mysite:plugin_wishlists:int_paypal:app_storefront_base

Resolution: Left to right. When SFCC resolves a file (e.g., controllers/Product.js), it searches each cartridge in path order and uses the first match. This enables non-destructive customization -- overlay specific files without modifying base cartridges.

Overlay constraints:

• File must have the same relative path inside cartridge/ to override
• Controllers can extend base controllers via module.superModule
• Templates override entirely (no partial merge)
• Static assets (CSS/JS) override entirely per file
• Resource bundles merge at the property level (keys from left cartridge win)

Cartridge Types

Controller Extension Pattern

Controllers can extend base behavior using module.superModule:

// Pattern: extend base controller
// Fetch live docs for server.extend() API
var server = require('server');
server.extend(module.superModule);
// Add or override route actions here

This avoids duplicating the entire base controller when you only need to modify one action.

Cartridge Metadata (cartridge.properties)

Required fields: cartridge ID and multi-language flag. Optional: version and compatibility version. Fetch live docs for the exact property key format (demandware.cartridges.<id>.*) before creating this file.

Build Tools

SFRA uses sgmf-scripts for compiling client-side SCSS and JS. Source files live in cartridge/client/default/ and compile to cartridge/static/default/. Webpack configuration maps entry points for JS bundles and SCSS compilation.

LINK Marketplace Certification

Deployment

Pattern: upload cartridge code to a code version on the sandbox/instance, then activate that version in Business Manager. Use WebDAV upload or the sfcc-ci CLI tool for automation.

# Pattern: scaffold a new cartridge
# Fetch live docs for sgmf-scripts CLI options
mkdir -p app_custom_mysite/cartridge/{controllers,models,scripts,templates/default}

Best Practices

Cartridge Organization

• Keep site-specific code in app_custom_*; reusable features in plugin_*.
• Minimize cartridge count -- each cartridge adds file resolution overhead.
• Match app_storefront_base directory layout for clean overlays.
• Use module.superModule to extend controllers rather than copying entire files.

Code Modularity

• Extract reusable functions to scripts/helpers/; keep controllers thin.
• Use models for business logic; templates for presentation only.
• Break large ISML files into <isinclude> components.
• Keep Page Designer components self-contained with clear input/output contracts.

Version Control and Deployment

• Increment cartridge.properties version on each release.
• Use semantic versioning tags in Git; maintain a CHANGELOG.
• Always deploy to sandbox first; activate code versions after validation.
• Use sfcc-ci for CI/CD pipeline integration.

Security

• Never commit secrets -- use Business Manager custom preferences or site preferences.
• Validate all inputs via form definitions and server-side checks.
• Follow OWASP guidelines, especially for payment integrations.
• Use service credentials (BM > Services) for external API keys.

Performance

• Minimize cartridge path length to reduce file resolution overhead.
• Serve only compiled, minified assets in production.
• Configure cache headers in Business Manager for static resources.
• Profile cartridge code with the SFCC code profiler before release.

Fetch the SFRA GitHub repo, B2C Commerce cartridge development docs, and LINK certification guidelines for exact directory conventions, build tool APIs, and deployment procedures before implementing.