B2C Commerce Script Modules
Starting in 13.6, B2C Commerce supports the Modules 1.1.1 CommonJS specification. Script modules within your storefront code can be located in cartridges. But unlike traditional B2C Commerce script files, the script modules within your storefront script code don't have to be located in cartridges.
This topic assumes that you’re familiar with the Modules 1.1.1 CommonJS specification.
A CommonJS-compliant B2C Commerce script module is either a script file (with a .js, .json, or .ds extension) or a directory containing script files. A module can hide private data, while exposing public objects and methods via a free variable named
A free variable is accessible within a function but isn’t a local variable defined within the function and isn't a parameter of the function. A free variable can be (but doesn't have to be) a global variable.
Before 13.6, you had to use the
importPackage methods to access other scripts; these methods automatically export everything into the global context. Now you can access CommonJS-compliant modules using the
require method. These modules don't automatically export everything into the global context.
Within a script file, you load a CommonJS-compliant B2C Commerce script module using the
TopLevel.global.require(path:String) method. When the module is loaded, you can use any of its exported variables or methods.
In the following example, the
mod1 module exports the
doit() method and the
aaa variable, but hides the
In the following example, the script loads the
mod1 module, retrieves the
aaa variable from the module, and runs the
TopLevel.global.require(path:String) method has different lookup behavior than the
require() function as specified in the Modules 1.1.1 CommonJS specification:
pathargument starts with "./" or "../", then it loads relative to the current module. The module can be a file or a directory. A file extension is acknowledged, but not required. If it's a directory, a
mainfile is expected in the directory.
mainfile is a file named
main, with either a .js, .ds, or .json extension.
package.jsonfile doesn’t contain a
mainproperty, then the script defaults to the
mainfile in the directory, if one exists. Access to parent files can't go beyond the top-level version directory. Access to other cartridges is allowed.
pathargument starts with "*/", it's a path relative to the start of the cartridge path.
pathargument starts with "~/", it's a path relative to the current cartridge in the cartridge path.
pathargument that prepends "dw", or that starts with "dw/", references B2C Commerce built-in functions and classes, for example:
loads the classes in the
utilpackage, which can be then used as follows:
pathargument that doesn't start with "./" or "../" is resolved as top-level module.
pathargument is used to find a folder in the top-level version directory, typically a cartridge itself, but it can also be a simple folder.
- If nothing is found, the
pathargument is used to look into a special folder (named
modules) in the top version directory. You can use this folder to manage different modules. For example, you can drop a module like
express.jsinto that folder.
TopLevel.global.require(path:String) method is used to reference a file, an optional file extension is used to determine the content of the file. Currently, B2C Commerce supports the following extensions, listed in priority order:
- .ds - B2C Commerce script file
- .json - JSON file
If you use JSON to define a module, the entire JSON object is implicitly exported via the
You can still use the
importPackage methods. However, it's recommended that you replace them with the
Assume that you have a script (used in SiteGenesis) with the following call to the
Further assume the following files and structure on the server:
This structure includes directories and files that are outside of cartridges. To upload such directories and files to a version directory, you can use the B2C Commerce Build Suite cartridge.
Regardless of where the script that requires a module is located, B2C Commerce finds the module as follows:
- First, B2C Commerce searches the
mymoduledirectory for a
- In this example, the
package.jsonis present, so B2C Commerce checks the value of the
mainproperty in the file.
- This property references the
myScript.dsfile, so B2C Commerce loads
myScript.dsas a module.
- If there’s no
package.jsonor if the
mainproperty is missing, B2C Commerce searches the directory for a
mainfile to load.
- If B2C Commerce finds a
mainfile, the file is loaded; otherwise, B2C Commerce continues to search.
- In this example, the
- Next, B2C Commerce finds the
mymodule.jsfile because it's in the top-level version directory. If there’s no file at this level, B2C Commerce continues to search.
- Last, B2C Commerce searches the
modulesdirectory in the top level for a
Although Salesforce provides a sophisticated fallback mechanism for scripts in the global namespace, we generally discourage polluting the global namespace with utility scripts. We recommend adding scripts to specific project cartridges.