orcaqubits/sf-b2c-cartridges

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

| Directory | Contents | Notes | |-----------|----------|-------| | controllers/ | Server-side JS route handlers | Each file exports route actions (e.g., Product-Show) | | models/ | Data models and business logic | Keep controllers thin; move logic here | | scripts/ | Utility helpers, middleware, services | Subdirs: helpers/, middleware/, services/ | | templates/default/ | ISML templates per locale | default/ is the fallback locale | | templates/resources/ | i18n .properties files | Resource bundles for Resource.msg() | | forms/default/ | XML form definitions | Server-side validation rules | | static/default/ | Compiled CSS, JS, images | Built from client/default/ source | | client/default/ | Source SCSS and JS | Input for webpack/sgmf-scripts build | | experience/components/ | Page Designer components | Visual merchandising building blocks |

Cartridge Naming Conventions

| Prefix | Purpose | Example | |--------|---------|---------| | app_custom_* | Site-specific customizations | app_custom_mysite | | plugin_* | Reusable feature modules | plugin_wishlists | | int_* | Third-party integrations | int_paypal, int_stripe | | bm_* | Business Manager extensions | bm_custom_admin | | app_storefront_base | Base SFRA cartridge | Core framework (do not modify) | | modules/ | Shared modules (non-cartridge) | Utility libraries consumed by cartridges |

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

| Type | Contains | When to Use | |------|----------|-------------| | Storefront | Controllers, templates, static assets | Customer-facing site logic | | Integration | Service definitions, API clients | Third-party system connections | | Plugin | Self-contained feature | Reusable cross-site features | | Business Manager | BM extensions, custom modules | Admin panel customizations |

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.

| Tool | Purpose | |------|---------| | sgmf-scripts --compile js | Compile client-side JavaScript | | sgmf-scripts --compile css | Compile SCSS to CSS | | sgmf-scripts --watch | Watch mode for development | | sfcc-ci | CLI for code upload and deployment automation |

LINK Marketplace Certification

| Category | Key Requirements | |----------|-----------------| | Technical | Compatible with latest SFRA; no hardcoded credentials; passes code profiler | | Documentation | Installation guide, BM configuration steps, troubleshooting guide | | Security | Input validation, CSRF protection, secure credential storage | | Testing | Unit tests, integration tests, performance benchmarks, multi-site compatibility |

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.

| Step | Action | |------|--------| | 1 | Upload code to a named code version via WebDAV or sfcc-ci | | 2 | Set the active code version in BM > Administration > Code Deployment | | 3 | Update cartridge path in BM > Site Settings if new cartridges were added | | 4 | Clear caches and verify storefront behavior |

# 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.