If you are building on Salesforce Commerce Cloud, you need to understand cartridges. Cartridges are the core modular unit of SFCC development — the equivalent of packages or modules in other frameworks. Every piece of custom code, every third-party integration, and every storefront template in SFCC lives in a cartridge.

This guide covers everything a developer needs to know to work effectively with SFCC cartridges.

What Is an SFCC Cartridge?

A cartridge is a self-contained directory that follows a specific file structure and can be activated on one or more SFCC sites. Cartridges contain:

Controllers — server-side JavaScript (SFCC's proprietary server framework) that handles route logic
Templates (ISML) — server-rendered HTML templates using SFCC's ISML templating language
Client-side assets — JavaScript, CSS, and images bundled via webpack (in SFRA)
Scripts — reusable server-side utility scripts
Static — fonts, images, and other static assets
Metadata — system object extensions and custom object definitions
Configuration — cartridge-specific settings and service definitions

The Cartridge Path

The cartridge path is the ordered list of cartridges active on a site. When SFCC needs to resolve a resource (a controller, template, or script), it searches cartridges from left to right along the cartridge path and uses the first match it finds.

This is how SFCC implements the override pattern:

app_custom_storefront:app_storefront_base

In this example, when a request comes in for a controller, SFCC checks app_custom_storefront first. If the controller exists there, it's used. If not, SFCC falls back to app_storefront_base.

This pattern is fundamental to SFCC development. You never modify base cartridges (like app_storefront_base). Instead, you create a custom cartridge that overrides only the files you need to change.

Storefront Reference Architecture (SFRA)

SFRA is Salesforce's recommended storefront architecture, introduced in 2018 as the replacement for the legacy Site Genesis framework. SFRA is itself delivered as a set of cartridges:

app_storefront_base — the core SFRA cartridge with all controllers, templates, and client-side code
modules — shared SFRA utilities
bm_app_storefront_base — Business Manager extensions for SFRA

For any SFRA project, you create a custom cartridge (e.g., app_custom_myproject) that overrides the specific controllers, templates, and scripts you need to customise.

Creating a Custom Cartridge

A minimal SFCC cartridge has this structure:

my_cartridge/
  cartridge/
    controllers/
    forms/
    models/
    scripts/
    static/
      default/
        css/
        js/
    templates/
      default/
  package.json

The cartridge/ directory is the root of all cartridge content. The package.json at the cartridge root (not inside cartridge/) defines the cartridge name used in the cartridge path.

Controllers in SFCC

SFCC controllers are server-side JavaScript files that define the route handlers for your storefront. In SFRA, controllers use the server module:

'use strict';

var server = require('server');
var page = module.superModule;
server.extend(page);

server.append('Show', function (req, res, next) {
    var viewData = res.getViewData();
    viewData.customData = 'hello world';
    res.setViewData(viewData);
    next();
});

module.exports = server.exports();

Key concepts:

server.extend(page) — inherit all routes from the parent cartridge's controller
server.append — add logic that runs after the parent route, without replacing it
server.replace — completely replace a parent route
server.prepend — add logic that runs before the parent route

ISML Templates

ISML (Internet Store Markup Language) is SFCC's server-side templating language. It extends HTML with SFCC-specific tags:

<isscript>
    var product = pdict.product;
</isscript>

<div class="product-name">
    <isprint value="${product.name}" encoding="html" />
</div>

<isif condition="${product.available}">
    <button class="add-to-cart">Add to Cart</button>
<iselse/>
    <p>Out of Stock</p>
</isif>

Key ISML tags:

<isscript> — execute server-side JavaScript
<isprint> — output a value (always use encoding="html" for user-generated content)
<isif> / <iselse> / <iselseif> — conditional rendering
<isloop> — iterate over collections
<isinclude> — include another ISML template
<isdecorate> — apply a page decorator template

Models and Scripts

In SFRA, models are server-side JavaScript classes that transform SFCC API objects into plain data objects suitable for passing to templates. They live in cartridge/models/.

Scripts are utility functions used by controllers and models. They live in cartridge/scripts/.

A clean SFRA architecture separates concerns:

Controllers handle routing and request/response orchestration
Models transform and prepare data
Scripts implement business logic
Templates render HTML

Cartridge Development Best Practices

Never modify base cartridges. Always create a custom cartridge to override only what you need. This keeps upgrades manageable.

Follow the override pattern consistently. Use server.append to add to routes, server.replace only when you need to completely change behaviour.

Keep cartridges focused. One cartridge per integration (payment gateway, loyalty programme, etc.) and one custom storefront cartridge. Avoid monolithic cartridges that mix concerns.

Use SFCC's link cartridge system for integrations. Most certified partner integrations are delivered as cartridges. Follow the integration documentation rather than building custom integrations from scratch.

Test in sandbox first. SFCC's multi-environment architecture (sandbox → staging → production) exists for a reason. Never test code changes directly in production.

Document custom Business Manager extensions. Custom system object extensions defined in cartridge metadata are often overlooked in documentation. Document what you've added and why.

Debugging SFCC Cartridges

SFCC provides several debugging tools:

Log Center in Business Manager — access custom dw.system.Logger output and system error logs
Prophet Debugger (VS Code extension) — the standard SFCC development tool for code upload, step-through debugging, and log streaming
Request Logger — capture and inspect HTTP requests through the SFCC pipeline
Pipeline Profiler — performance profiling for legacy pipeline code

For modern SFRA development, Prophet Debugger is the essential tool. Configure it with your SFCC sandbox credentials to enable real-time code sync and breakpoint debugging.

Getting Certified in SFCC Development

If you are serious about SFCC as a career, consider the official Salesforce certifications:

B2C Commerce Developer — the foundational certification for SFCC developers
B2C Commerce Architect — senior-level certification covering solution design and architecture

Both certifications are available through Trailhead and require practical knowledge of cartridge development, Business Manager configuration, and SFCC's API layer.

SFCC Cartridge Development: The Complete Guide for Developers