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 by accident
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 in two moments:
- When a project opens. About 5 seconds after opening, it checks for cartridges that are not linked yet and not ignored
- On demand. Click Find New Cartridges in the main toolbar, or press
Ctrl+Alt+](Cmd+Option+]on macOS)
Review what was found
The Found N cartridges dialog lists each cartridge with its Path. Every row starts with Link to project checked
Link or ignore
Keep Link to project for the cartridges you work on. Check Ignore for the ones you don't, for example copies in a build or test folder. Ignored cartridges are hidden from the next search
Confirm
Click OK. Linked cartridges get the cartridge icon in the Project view and can be uploaded right away
The dialog that opens on project start has a Do Not Show Again checkbox. Check it to stop the startup check. Find New Cartridges in the toolbar still works. When there is nothing new, it shows "New Cartridges Not Found"
The search goes up to five folders deep below each content root. It skips folders marked Excluded in the IDE and build or tool folders such as node_modules, .git, .idea, test and gulp. Link a cartridge that sits deeper by hand, see the next section
app_custom
package.json
Link folders by hand
Right-click a folder in the Project view and open Mark Directory as. The plugin adds its items at the top of that submenu
| 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 again, so you can link them |
| 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 |
A folder is detected as a cartridge only by its cartridge subfolder. B2C modules and the modules folder are never linked automatically, mark them yourself. Until it is linked, a modules folder next to your cartridges shows a dimmed modules icon
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 lists the names and asks whether to link the new ones and remove the existing ones. 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, links the cartridge to the project and, with the upload option on, sends it to the instance. Add the cartridge to the site's cartridge path in Business Manager before the storefront uses it
Review linked roots
More › Instance › Cartridges and B2C Modules Root Paths opens every linked root in one dialog
| Tab | Shows |
|---|---|
| Cartridges | Linked cartridges. Add or remove them with + and - |
| Ignored Cartridges | Cartridges you chose to ignore. Remove one to see it in the next search again |
| B2C Modules | Linked B2C module folders |
| Modules (Global Modules) | The linked modules folder. "There could be only one Modules Root" |
Each tab title shows how many items it has. The dialog also links to the Salesforce guides on cartridges, SFRA, customizing SFRA, the B2C Commerce API and script modules
Salesforce B2C Commerce project view
The Project tool window gets a Salesforce B2C Commerce view in its view switcher. It shows only what the plugin works with: one root node and the linked cartridges and modules under it
- 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
This is the quickest way to check that the plugin sees the cartridges you expect
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 | |
templates folder | |
| Resource bundles folder | |
Controller in cartridge/controllers | |
Model in cartridge/models | |
Form definition in cartridge/forms | |
| Pipeline XML | |
| ISML template | |
DemandwareScript .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 an excluded, build or test folder. Link it with Mark Directory as › Cartridge Root |
| A cartridge never shows up again after a search | It is on the ignore list. Use Remove Cartridge From Ignore List or the Ignored Cartridges tab |
[NOT ALLOWED] ... Please link cartridge '...' to your project in B2C Sync Log | The file's cartridge is not linked. Link it, then save the file again |
| 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