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:
| Root | Icon | What it is |
|---|---|---|
| Cartridge Root | A cartridge: any folder that has a cartridge subfolder, for example app_custom/cartridge | |
| B2C Module Root | A folder outside any cartridge that is deployed next to your cartridges, for example a shared script module | |
| Modules (Global Modules) Root | The 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
Link or ignore
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,testandtests - Any folder whose path contains
gulp,node_modules,/cartridge/testor/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
| Kind | Suggested 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
Link folders by hand
Right-click a folder in the Project view and open Mark Directory as
| Item | Shown for | What it does |
|---|---|---|
| Cartridge Root | Folders that have a cartridge subfolder | Links the cartridge. You can select several cartridges at once |
| Unmark as Cartridge Root | Linked cartridges | Unlinks them. The files stay on disk and on the instance |
| Remove Cartridge From Ignore List | Ignored cartridges | Makes them available to link again |
| B2C Module Root | Folders that are not a cartridge and not inside one | Links the folder as a B2C module. Unmark as B2C Module Root removes it |
| Modules (Global Modules) Root | A single folder named modules | Links 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
| Option | Default | What it does |
|---|---|---|
| Cartridge name | Letters, digits, _ and - only | |
| Upload to B2C Commerce Instance | On | Uploads the new cartridge to the active connection's code version |
| Create .tern-project | Off | Adds a .tern-project file for editors that use Tern |
| Create hooks.json | Off | Adds 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
| Kind | Shows |
|---|---|
| Cartridges | Linked cartridges. Add Cartridges… links more, Find New Cartridges searches the project |
| B2C Modules | Linked B2C module folders. Add Modules… links more |
| Global Modules | The linked modules folder. Choose Folder… replaces it, since a project links one |
| Ignored Folders | Folders 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
To switch to it:
- Open the Project tool window,
⌘1on macOS orAlt+1on Windows and Linux - Click the tool window's title, Project
- 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
| Icon | Means |
|---|---|
| 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
| Symptom | What to do |
|---|---|
| A cartridge is not found by Find New Cartridges | Check 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 disabled | A search is still running. Wait for the background task to finish, or cancel it |
| A cartridge never shows up again after a search | It 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 Sync | The file's cartridge is not linked. Link it, then save the file again |
| A B2C module is not suggested | It 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 menu | The folder is a cartridge, is inside one, or is inside modules |
| Modules (Global Modules) Root is missing | Select 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 missing | No cartridge is linked yet. Run Find New Cartridges first |
Related
Overrides
Copy or extend a file in another cartridge
Site Scopes
Choose which site's cartridge path the IDE follows
Cartridge Path Editor
Reorder, add and remove the cartridges of a local site.xml
Deploy Code
Upload every linked cartridge and module at once
Module Resolution
How require, */ and module.superModule resolve