Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 28 ยท Cartridges and Architecture

Cartridges and the Cartridge Path

Understand SFCC cartridges: folder structure, app_storefront_base, plugin and int_ cartridges, and how the cartridge path decides which file wins, with runnable lookup demos.

A cartridge is B2C Commerce's unit of code: a folder with a known structure that holds controllers, templates, scripts, forms and static files. A storefront is not one big application. It is a stack of cartridges, and the cartridge path decides in which order the platform searches them. That single idea explains how you customize a reference storefront without editing its files, and it is the first thing to understand when "my change doesn't show up".

This lesson shows the folder layout, the usual cartridge types, and the lookup rules. The next lesson, SFRA Architecture and Request Flow, builds on it to explain how routes are extended across cartridges.

Cartridges run only on the platform, so the real code here is read-only. The runnable examples are stand-ins: a small function that resolves a file along a cartridge path the way the platform does conceptually. The real resolver has more cases than we model (for example locale-specific template folders).

What a cartridge looks like

On disk, a cartridge is a folder containing a cartridge folder (note the repetition) plus project files for your tools. Inside cartridge, folder names have meaning:

TEXT
app_custom/
  package.json
  cartridge/
    app_custom.properties
    controllers/        server-side routes (SFRA)
    models/             data shaping classes
    scripts/            helpers, hooks, jobs, services
    templates/
      default/          ISML templates (and locale folders next to default)
    forms/default/      form definitions (XML)
    static/default/     compiled CSS, JS, images served to browsers
    client/default/     source JS and SCSS (compiled by npm)
    experience/         Page Designer components

The platform finds files by their path inside the cartridge, such as controllers/Product.js or templates/default/product/detail.isml. The cartridge's own name is not part of the lookup key. That is what makes layering possible.

The usual cartridge types

You will meet names like these in almost every project:

Cartridge Role
app_storefront_base The SFRA reference storefront: base controllers, models, templates, styles
plugin_* (for example plugin_wishlists) Optional features from Salesforce or partners, designed to layer on top of the base
int_* Integration cartridges that connect an external system (payment, tax, search, ERP)
app_custom (project-specific) Your overlay: customizations for this client
modules Shared server-side modules available to all
bm_* Cartridges extending Business Manager itself

Two naming conventions matter in practice. app_ cartridges hold storefront behavior, int_ cartridges hold connectors. A new project normally creates its own overlay cartridge rather than editing app_storefront_base, so upgrades from Salesforce remain possible.

The cartridge path

Each site has a cartridge path: a colon-separated list set in Business Manager at Administration > Sites > Manage Sites > (site) > Settings:

TEXT
app_custom:plugin_wishlists:int_payments:app_storefront_base

The platform searches from left to right and the first cartridge that contains a matching file wins. So app_custom can replace any file in app_storefront_base just by having a file at the same relative path. Files that only exist in one cartridge are found wherever they sit in the path.

flowchart LR
    R["Request needs<br/>controllers/Cart.js"] --> A["app_custom"]
    A -->|"found? use it"| Done["Use this file"]
    A -->|"not found"| B["plugin_wishlists"]
    B -->|"not found"| C["int_payments"]
    C -->|"not found"| D["app_storefront_base"]
    D --> Done

The lookup stops at the first cartridge on the path that has the file.

There is a separate cartridge path for Business Manager (for bm_ cartridges), and a storefront path per site, so the same instance can show different behavior on different sites by changing the order.

Referring to files: require paths

Inside server-side JavaScript you load other files with require. Two special prefixes depend on the cartridge path:

  • */cartridge/scripts/helpers/pricing searches the whole path for that file: it finds the highest-priority version.
  • ~/cartridge/scripts/helpers/pricing looks only in the current cartridge (the one containing the file that calls require).
JavaScript
// Read-only: typical SFRA requires
var ProductFactory = require('*/cartridge/scripts/factories/product'); // wins by path order
var helper = require('~/cartridge/scripts/helpers/badges');            // this cartridge only
var base = module.superModule;                                          // the next file down the path

Using */ everywhere in overlay code means your own overrides and plugins are picked up automatically. The module.superModule object (used by controllers) is the file with the same path in the next cartridge further right on the path. We use it heavily in the next lessons.

Overlay, plugin and integration cartridges together

A real path often looks like this: the project overlay on the left, plugins in the middle, and the base on the right. A plugin written well adds new files and extends existing routes instead of replacing them, so it can sit beside other plugins. If two cartridges replace the same file, only the left one is used. This is the main cause of a feature mysteriously stopping when a new plugin is added. The remedy is to extend with module.superModule instead of copying and replacing files.

JS Resolve a file along a cartridge path (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Debugging the cartridge path

When a change does not appear, check these in order:

  1. Is your cartridge in the site's cartridge path (and is it the right site)?
  2. Is another cartridge to the left of yours that also has this file?
  3. Did you upload to the active code version?
  4. Is the page served from the page cache (see Caching and Performance)?
  5. Did you spell the path exactly, including folder case? Treat paths as case-sensitive, even if your laptop is not.
JS Find shadowed files and test a reorder (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second report shows how swapping two cartridges changes which controllers/Product.js runs. That is why cartridge order is part of your release checklist.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. With the path "app_custom:plugin_x:app_storefront_base", which cartridge supplies controllers/Cart.js if all three contain it?

    The platform searches left to right and uses the first match, so app_custom wins. Others run only if the winner calls them through module.superModule.
  2. 2. What does the "/" prefix in require('/cartridge/scripts/x') do?

    The "~/" prefix is cartridge-local. The "*/" prefix is the one that follows the whole cartridge path.
  3. 3. Why create an overlay cartridge instead of editing app_storefront_base directly?

    Customizing in your own cartridge keeps your diff small and upgrades manageable.
  4. 4. A new plugin makes an existing feature stop working. What is a likely cause?

    Two cartridges with the same file path means only the leftmost is used. Extending instead of replacing avoids the clash.

Summary

  • A cartridge is a folder (cartridge/controllers, models, scripts, templates, static, forms) and a site stacks several of them.
  • The site's cartridge path is searched left to right and the first matching file wins.
  • Typical types: app_storefront_base, plugin_*, int_*, bm_* and your own overlay.
  • */cartridge/... follows the path, ~/cartridge/... stays in the current cartridge, module.superModule is the same file further right.
  • When a change is missing, check the site path, shadowing files, the active code version and the page cache.

Next: SFRA Architecture and Request Flow