Skip to Content

Module Resolution

How Intellij SFCC completes and resolves require paths, the */ and ~/ prefixes, B2C modules and module.superModule along the cartridge path

SFCC's require doesn't work like Node. Intellij SFCC resolves paths the way the server does, so completion, Go to Declaration and types land on the file the storefront loads

require targets, module.superModule, form links and Search Everywhere results follow the cartridge path of the site picked in the status bar, so they land on the file the server would load

Require paths

PathResolves toExample
dw/...A Script API class, see API & Typesrequire('dw/catalog/ProductMgr')
./..., ../...A file relative to the current filerequire('./helpers/cartHelpers')
~/...A file in the current cartridgerequire('~/cartridge/scripts/helpers/basketHelpers')
*/...The first cartridge on the site's cartridge path that has the filerequire('*/cartridge/scripts/helpers/productHelpers')
<cartridge>/...A file in the named cartridgerequire('app_storefront_base/cartridge/controllers/Cart')
A bare nameA B2C module or a package in the global modules folderrequire('server')

Completion offers .js, .ds and .json files and leaves the extension out, as the server does

Complete paths

require paths complete from every linked cartridge. Each item shows the cartridge that owns it; the list opens with Ctrl+Space

Type inside require('') and press Ctrl+Space:

  • An empty or one-word path lists linked cartridges, marked Cartridge, and the B2C and global modules you can require by name, never npm packages or the files beside the script
  • After */, ~/, ./ or a cartridge name, completion walks the folders and files below it
  • Each item shows the cartridge or module that owns it

Go to the file the server loads

Cmd+Click or Cmd+B (Ctrl+Click or Ctrl+B) on a require path opens its target. For a */ path the targets depend on the site scope:

ScopeTargets
A site, for example RefArchThe cartridges on that site's path, in path order. The first is the file the server loads
Global scopeEvery linked cartridge that has the file. The IDE asks you to pick one

Pick your site in the status bar to match the storefront

Paths from a resource bundle

A module path kept in the require bundle folds to the path the bundle holds. Cmd+Click on require opens that script, and completion lists its exports with the cartridge they come from

Some storefronts keep module paths in a require.properties bundle, so a brand or locale can swap the script without a code change:

app_custom/cartridge/templates/resources/require.properties
tax.helper=int_tax/cartridge/scripts/helpers/TaxHelper.js
app_custom/cartridge/scripts/hooks/cart/calculateTax.js
var tax = require(Resource.msg('tax.helper', 'require', null));

require(Resource.msg(key, 'require', null)) resolves like the same path written as a literal:

What you doWhat happens
Open the fileThe call reads require("int_tax/cartridge/scripts/helpers/TaxHelper.js"). Click the text to open the call, and click the marker in the gutter to fold it back
Cmd+Click on requireOpens the script the path names, by the rules of Require paths
Cmd+Click on the keyOpens the key's entries in the bundle
Type tax.Lists the script's exports, typed, with the cartridge they come from
  • The bundle value is read as B2C Commerce reads it: the default locale's file wins, then the first cartridge on the cartridge path
  • A value that starts at the cartridge folder, such as cartridge/scripts/guard, names the script in the calling cartridge
  • A key no bundle has falls back as on the server: to the default, or to the key itself when the default is null. A key that is a script path, such as 'int_tax/cartridge/scripts/helpers/TaxHelper.js', resolves and folds to that path, Cmd+Click on it opens the script, and templates don't report it as unknown
  • module.exports = require(Resource.msg(...)) passes the types on to the scripts that require that file
  • It works in .js, .ds and .ts files and in <isscript>. Resource.msgf and other bundles are left as strings

Every other static Resource.msg and Resource.msgf call folds to its message too, see Resource bundles. Both need a license or trial

module.superModule

module.superModule is the same file in a cartridge further right on the cartridge path. SFRA overrides use it to extend the original instead of copying it. The path has to match case for case, as on the instance: productHelpers.js doesn't find ProductHelpers.js

app_custom/cartridge/scripts/helpers/productHelpers.js
var base = module.superModule;

function getBadge(product) {
    return product.custom.badgeText || null;
}

base.getBadge = getBadge;

module.exports = base;

base. completes the original's exports, and Cmd+Click on superModule opens the original. With more copies it opens the next one down, see Members through every override

Members through every override

A require that lands on an override still knows the whole chain. Completion lists the members of every copy down the cartridge path, and Cmd+Click follows each module.superModule to the copy that defines the member, or to the override that adds it

A file that requires an override also gets the members of every copy it extends, through as many overrides as the cartridge path has. Here RefArch's path is app_custom:plugin_reviews:app_storefront_base, each with its own productHelpers.js:

What you doWhat happens
Type productHelpers. after requiring */cartridge/scripts/helpers/productHelpersLists getBadge from app_custom, getRating from plugin_reviews and the original's functions from app_storefront_base, each with that cartridge on the right
Cmd+Click getProductType, which only the original definesFollows module.superModule through both overrides and opens it in app_storefront_base
Cmd+Click getRating, added by plugin_reviews with base.getRating = function (product) {…}Opens in plugin_reviews, where it is added

The same works for base. inside an override, for require paths naming the override's cartridge, and in files you haven't opened

The next copy follows the site scope: on a site, the next cartridge on its path that has the file. In Global scope, or for a cartridge not on the selected site's path, copies that extend another come first and the original last, so the chain never loops back

Adding, moving or deleting a copy updates require targets and path completion right away

Controllers use server.extend(module.superModule), see SFRA Controllers. Overrides creates both kinds of file for you

Fallbacks and copy loops

Two more SFRA patterns keep the members of every copy below:

Codebase. and require of the script list
var base = module.superModule || {};, then base.getBadge = getBadge;The exports of every copy below and the members you add
module.exports = { getBadge: getBadge };, then module.exports[key] = base[key] in a loop over baseThe literal's members and every export below that the literal doesn't name, each opening in the copy that defines it

See superModule chains

B2C modules and global modules

A bare name such as require('server') loads a top-level folder next to your cartridges or a package in the modules folder. In the IDE these come from roots you mark:

RootMark it withThen
B2C Module Root Mark Directory as › B2C Module RootIts scripts complete by module name, with the module icon
Modules (Global Modules) Root Mark Directory as › Modules (Global Modules) RootIts packages complete by name, for example server from SFRA's modules/server

See Cartridges & Modules for the rules

Troubleshooting

SymptomWhat to do
A */ path opens the wrong cartridgeSelect the site in the site scope widget. In Global scope every copy is a target
require('server') is unresolvedMark SFRA's modules folder as Modules (Global Modules) Root
A cartridge is missing from completionLink it in Cartridges & Modules
module.superModule resolves to nothingNo other linked cartridge has a file at the same path below cartridge/, or the current cartridge is last on the site's path
A member of the original doesn't complete through an overrideThe override has to return what it extends: module.exports = base; after var base = module.superModule;, or module.exports = module.superModule;. With a site selected, the cartridge that defines the member must be on that site's path
A site's path names a cartridge that isn't in the projectAdd its source to the project and link it
require(Resource.msg(...)) doesn't resolve or foldThe key and bundle must be literals, and indexing must finish. The key must be in a require.properties of a linked cartridge, or the key (or the default) must be a path to a script

On this page