@commerce-klaus/babel-plugin-sfcc-modules

A Babel plugin that resolves Salesforce Commerce Cloud (SFCC) server-side module patterns for Babel-based runtimes and tests.

This package continues the original babel-plugin-sfcc-modules under the Commerce Klaus organization.

TL;DR

.babelrc

{
  "plugins": [
    [
      "@commerce-klaus/babel-plugin-sfcc-modules",
      {
        "cartridgePath": ["app_brand", "app_core", "app_storefront_base"],
        "basePath": "./cartridges"
      }
    ]
  ]
}

Shared resolution model

SFCC resolves server-side modules in the context of an ordered cartridge path. Entries on the left have higher precedence, so the order is part of application behavior rather than a filesystem detail.

• */cartridge/... selects the first matching module in cartridge-path order.
• ~/cartridge/... selects a module from the importing file's own cartridge.
• <cartridge>/cartridge/... selects a module from one named cartridge.
• module.superModule selects the next matching implementation after the current cartridge.
• dw/* refers to platform APIs and is not resolved from the project filesystem.

Commerce Klaus shares these rules across its ESLint, TypeScript, Babel, Vite, and Vitest integrations. See Understanding SFCC module resolution for the complete model, examples, and edge cases.

Commerce Klaus can read these options from one shared commerce-klaus.config.ts or .js file. Package options remain supported and override the central values.

Why this plugin exists

This plugin rewrites SFCC module patterns to relative require paths that Node.js can load, without requiring additional runtime shims.

Features

• Resolves require("*/...") against cartridge order.
• Resolves require("~/...") against the caller's own cartridge.
• Resolves module.superModule to the next matching cartridge implementation.
• Supports cartridge order via explicit cartridgePath or inferred order fallback.
• Designed for Babel-based test/tooling pipelines.

Installation

This plugin supports Babel 7 and 8 and declares @babel/core and @babel/types as peer dependencies. Install matching compatible Babel packages in your project.

pnpm

pnpm add -D @commerce-klaus/babel-plugin-sfcc-modules

yarn

yarn add -D @commerce-klaus/babel-plugin-sfcc-modules

npm

npm install -D @commerce-klaus/babel-plugin-sfcc-modules

Vite+

vp install -D @commerce-klaus/babel-plugin-sfcc-modules

Usage

Add to your Babel configuration:

.babelrc

"plugins": [
  ["@commerce-klaus/babel-plugin-sfcc-modules", {
    "cartridgePath": [
      "app_brand",
      "app_core",
      "app_storefront_base"
    ],
    "basePath": "./cartridges"
  }]
]

Example with cartridge order inferred from site.xml (custom-cartridges):

.babelrc

"plugins": [
  ["@commerce-klaus/babel-plugin-sfcc-modules", {
    "basePath": "./cartridges",
    "siteTemplatePath": "./sites/site_template",
    "site": "RefArch"
  }]
]

Example with explicit env-style override (envCartridgePath):

.babelrc

"plugins": [
  ["@commerce-klaus/babel-plugin-sfcc-modules", {
    "basePath": "./cartridges",
    "envCartridgePath": "app_brand:app_core:app_storefront_base"
  }]
]

Options

Option	Type	Description
cartridgePath	Array	ordered cartridge path used for lookup (optional)
basePath	string	cartridge directory override; defaults to central config, then cartridges
cwd	string	working directory used to resolve relative paths
siteTemplatePath	string	path to the site-template root containing sites/<site>/site.xml
site	string	site id used to read custom-cartridges from site.xml
solutionConfigPath	string	path to cartridges/jsconfig.json used for reference-based cartridge order
envCartridgePath	string	colon-separated cartridge order override (same as SFCC_CARTRIDGE_PATH)
configFile	string | false	explicit central config path, or false to disable discovery

Commerce Klaus uses the following precedence when determining cartridge order:

1. An explicit cartridgePath option.
2. An envCartridgePath option, the Salesforce SFCC_CARTRIDGES environment variable, or the legacy SFCC_CARTRIDGE_PATH environment variable.
3. References in the configured solution jsconfig.json.
4. The site's custom-cartridges value in site.xml.
5. A deterministic alphabetical filesystem fallback.

The first source that produces entries wins. SFCC_CARTRIDGES takes precedence over SFCC_CARTRIDGE_PATH, and both comma- and colon-separated values are accepted. Missing cartridge directories are filtered out, and valid results are represented internally as absolute cartridge-root paths.

For reproducible CI and local behavior, prefer an authoritative project source such as an explicit path, solution references, or site metadata. The alphabetical fallback is convenient for initial setup, but it cannot express intentional override precedence.

Resolution behavior

1. require("*/...")

Searches all cartridges in order and rewrites to the first matching file as a relative require path.

2. require("~/...")

Resolves only in the current file's cartridge and rewrites to a relative require path.

3. module.superModule

Resolves to the next matching module in cartridge order and rewrites to require("<relative>").

If no fallback cartridge module exists, it is rewritten to undefined.

Babel notes

• Use the plugin in your Babel plugins array for test/runtime transforms.
• The plugin rewrites import-like patterns in transformed source; it does not alter SFCC runtime behavior itself.
• For non-test frontend bundles, prefer native bundler alias mechanisms where possible.

Relationship to @commerce-klaus/vite-plugin-sfcc-modules

Topic	@commerce-klaus/babel-plugin-sfcc-modules	@commerce-klaus/vite-plugin-sfcc-modules
Transformation layer	Babel	Vite transform pipeline
Runtime setup	Babel-driven test/tooling runtime	Native Vite/Vitest
Main use case	Existing Babel-based SFCC workflows	Modern Vite-based SFCC workflows

Warning

You shouldn't use it for frontend code. There are better alternatives to deal with a cartridge path, NODE_PATH and the handling of frontend assets in sgmf-scripts.

In my opinion the best way to handle frontend code is to have a clean configuration of Webpack aliases.

The cartridge path concept isn't common for Node.js/frontend code. This plugin will work for it but I won't officially support it.

Development

This repository uses Vite+ (vp):

vp install
vp check
vp test
vp run build

License

MIT