Skip to Content

Cartridges & Modules

Find and link cartridges, mark B2C modules and the global modules folder, create new cartridges and review what the plugin works with

Intellij SFCC works only with the folders you link to the project. A linked cartridge gets Auto Upload, Deploy Code, the debugger, cartridge-aware completion and navigation. A cartridge that is not linked is left alone, so test fixtures, copies and vendor folders never reach your instance

There are three kinds of linked roots:

RootIconWhat it is
Cartridge RootA cartridge: any folder that has a cartridge subfolder, for example app_custom/cartridge
B2C Module RootA folder outside any cartridge that is deployed next to your cartridges, for example a shared script module
Modules (Global Modules) RootThe modules folder whose packages scripts can require by name. A project has only one

Find new cartridges

The plugin looks for cartridges, B2C modules and the global modules folder that are not linked yet and not ignored:

  • When a project opens. A notification lists what it found. Review… opens the dialog, Link All links everything when no name is taken, and Don't Ask Again turns the startup check off for this project
  • On demand. Click Find New Cartridges in the main toolbar, or press Cmd+Option+] on macOS (Ctrl+Alt+] on Windows and Linux). The search runs as a background task you can cancel

Review what was found

The dialog lists the folders under their parent folder. B2C modules and the modules folder show their kind next to the name. Of folders that share a name, the first is checked, and a name that is already linked waits for you to check it

Uncheck what you don't work on and it comes back with the next search. Press Delete or click Ignore on a row, or on a folder for all its rows, to stop suggesting it. Show ignored brings ignored folders back

Confirm

Click Link. Linked folders get their icon in the Project view and can be uploaded right away

When there is nothing new, Find New Cartridges says "No new cartridges or modules"

The search goes up to 20 folders deep below each content root and 10,000 folders in all. It skips cartridge contents, folders marked Excluded in the IDE and:

  • Folders named .git, .idea, node_modules, data_impex, gulp_builder, js, test and tests
  • Any folder whose path contains gulp, node_modules, /cartridge/test or /cartridge/tests

Link a cartridge in a skipped folder by hand

How modules are found

Modules are looked for only next to your cartridges, in the folder that holds them, where the instance finds them in a code version. Folders of tests and fixtures are skipped

When the project opens, a notification lists the cartridges and modules it found. Review… opens the dialog, where the vendor copy is ignored and Link links the rest
KindSuggested when
Modules (Global Modules) The folder is named modules and holds a script or a folder of scripts
B2C module Its main.js, main.ds or main.ts is server code: CommonJS with no Node built-ins, DOM or ES modules. Or its package.json main is such a script and its scripts use the B2C Commerce API

A folder with a node_modules folder, an index.html, or a webpack, Vite, Rollup, Babel, Jest, Playwright, gulp or TypeScript config is a build tool, not a module

Right-click a folder in the Project view and open Mark Directory as

ItemShown forWhat it does
Cartridge Root Folders that have a cartridge subfolderLinks the cartridge. You can select several cartridges at once
Unmark as Cartridge Root Linked cartridgesUnlinks them. The files stay on disk and on the instance
Remove Cartridge From Ignore List Ignored cartridgesMakes them available to link again
B2C Module Root Folders that are not a cartridge and not inside oneLinks the folder as a B2C module. Unmark as B2C Module Root removes it
Modules (Global Modules) Root A single folder named modulesLinks the global modules folder. Unmark as Modules (Global Modules) Root removes it

Find New Cartridges suggests the B2C modules and the modules folder next to your cartridges. Mark any other module folder yourself. Until it is linked, a modules folder next to your cartridges shows a grey modules folder , and a red one once Find New Cartridges ignores it

One cartridge per name

The instance has one cartridge per name, so the project links one too. When you link a cartridge whose name is already linked from another folder, Duplicated Cartridges Found asks what to keep. Answer Yes to switch to the new folder, or No to keep the current one

Create a cartridge

Right-click the folder that should hold it and choose New › Cartridge

OptionDefaultWhat it does
Cartridge nameLetters, digits, _ and - only
Upload to B2C Commerce InstanceOnUploads the new cartridge to the active connection's code version
Create .tern-projectOffAdds a .tern-project file for editors that use Tern
Create hooks.jsonOffAdds a hooks.json file and a package.json that points to it

The plugin creates <name>/.project and <name>/cartridge/<name>.properties and links the cartridge to the project. Add the cartridge to the site's cartridge path in Business Manager before the storefront uses it

Review linked roots

More › Instance › Cartridges and Modules… opens every linked root in one dialog, with each kind and its count on the left

KindShows
CartridgesLinked cartridges. Add Cartridges… links more, Find New Cartridges searches the project
B2C ModulesLinked B2C module folders. Add Modules… links more
Global ModulesThe linked modules folder. Choose Folder… replaces it, since a project links one
Ignored FoldersFolders that Find New Cartridges skips. Stop Ignoring lets the next search offer them again

Folders are grouped under the folder they are in, relative to the project. Type to filter by name or folder. Select folders and press Delete or Remove to unlink them, or right-click for Copy Path and your file manager's reveal action. A folder gone from disk shows Folder not found in red

Adding follows One cartridge per name: a folder whose name is linked replaces the linked one, and a line under the list says what was added, replaced or skipped and why. Nothing changes until you click Save, and Find New Cartridges waits until then because it closes the dialog

Salesforce B2C Commerce project view

The Project tool window gets a Salesforce B2C Commerce view in its view switcher. It shows only the linked cartridges and modules, under one root node

Click the Project tool window's title and pick Salesforce B2C Commerce. The view keeps only your linked cartridges and modules under one root, and META lists the site archive XML

To switch to it:

  1. Open the Project tool window, ⌘1 on macOS or Alt+1 on Windows and Linux
  2. Click the tool window's title, Project
  3. Pick Salesforce B2C Commerce

The IDE keeps the view you picked for the project. Switch back from the same title. Show B2C project view on the Getting Started tab opens it in one click

  • The root is named after the project in the global scope, or after the selected site when a site scope is set
  • Next to the name it shows the totals, for example "(14) cartridges 12 | b2c modules 1 | modules 1"
  • With a site selected, cartridges follow that site's cartridge path order, the ones not on the path come after them, then B2C modules and the modules folder
  • META beside the root holds the site archive XML of the project by organization and site, the same tree as B2C Metadata

Pipelines by group and start node are in B2C Entry Points and Pipeline Groups

The cartridge of the open file

A chip at the top right of the editor, next to the inspection counter, names the cartridge of the open file. Its tooltip says whether the cartridge is on the selected site's cartridge path. Click it to select the cartridge folder in the Project view

Folder and file icons

Linked roots and common SFCC folders and files get their own icons in the Project view, in editor tabs and in the Git views

IconMeans
Linked cartridge
Cartridge that is not linked yet
Ignored cartridge
Linked B2C module
Linked modules folder
Modules folder that is not linked yet
Ignored modules folder
templates folder
Resource bundles folder
Controller in cartridge/controllers
Model in cartridge/models
Form definition in cartridge/forms
Pipeline XML
ISML template
Digital Script .ds file
hooks.json
steptypes.json

Troubleshooting

SymptomWhat to do
A cartridge is not found by Find New CartridgesCheck that it has a cartridge subfolder and isn't inside a skipped folder such as js, test, node_modules or .intellij-sfcc/transpiled. Link it with Mark Directory as › Cartridge Root
Find New Cartridges is disabledA search is still running. Wait for the background task to finish, or cancel it
A cartridge never shows up again after a searchIt is on the ignore list. Use Remove Cartridge From Ignore List, or Stop Ignoring under Ignored Folders in Cartridges and Modules
[NOT ALLOWED] ... Please link cartridge '...' to your project in B2C SyncThe file's cartridge is not linked. Link it, then save the file again
A B2C module is not suggestedIt has to sit next to your cartridges and run on the server, see How modules are found. Link it with Mark Directory as › B2C Module Root
B2C Module Root is missing from the menuThe folder is a cartridge, is inside one, or is inside modules
Modules (Global Modules) Root is missingSelect exactly one folder, and it must be named modules
Deploy says "Please merge your duplicate cartridges into one or exclude any of them"Two linked folders use the same cartridge name. Keep one of them
Plugin toolbar buttons are missingNo cartridge is linked yet. Run Find New Cartridges first

On this page