---
url: /commerce-klaus/packages/babel-plugin-sfcc-modules.md
---
[![NPM version][npm-image]][npm-url] [![Downloads][npm-downloads-image]][npm-url]

# @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

```json{3-8} [.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](/guide/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](/guide/project-configuration).
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.

::: code-group

```sh [pnpm]
pnpm add -D @commerce-klaus/babel-plugin-sfcc-modules
```

```sh [yarn]
yarn add -D @commerce-klaus/babel-plugin-sfcc-modules
```

```sh [npm]
npm install -D @commerce-klaus/babel-plugin-sfcc-modules
```

```sh [Vite+]
vp install -D @commerce-klaus/babel-plugin-sfcc-modules
```

:::

## Usage

Add to your Babel configuration:

```json{2-9} [.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`):

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

Example with explicit env-style override (`envCartridgePath`):

```json{2-5} [.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

![kitten.png](https://github.com/jenssimon/babel-plugin-sfcc-modules/raw/main/kitten.png)

You shouldn't use it for frontend code. There are better alternatives to deal with a cartridge path, [NODE_PATH](https://nodejs.org/api/modules.html#modules_loading_from_the_global_folders) and the handling of frontend assets in [sgmf-scripts](https://www.npmjs.com/package/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`):

```bash
vp install
vp check
vp test
vp run build
```

## License

MIT

[npm-url]: https://www.npmjs.com/package/@commerce-klaus/babel-plugin-sfcc-modules

[npm-image]: https://badgen.net/npm/v/@commerce-klaus/babel-plugin-sfcc-modules

[npm-downloads-image]: https://badgen.net/npm/dw/@commerce-klaus/babel-plugin-sfcc-modules