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

# @commerce-klaus/vite-plugin-sfcc-modules

A Vite plugin that resolves Salesforce Commerce Cloud (SFCC) server-side module patterns.

This package continues `vite-plugin-sfcc-modules` under the Commerce Klaus organization.
It originates from `@commerce-klaus/babel-plugin-sfcc-modules` and is the port to a modern Vite ecosystem. The goal is the same DX for SFCC module resolution, but natively in Vite/Vitest without a Babel runtime layer.

## TL;DR

```ts{1,4-8} [vite.config.ts]
import sfccModules from "@commerce-klaus/vite-plugin-sfcc-modules"

export default defineConfig({
  plugins: [
    sfccModules({
      cartridgePath: ["app_brand", "app_core", "app_storefront_base"],
      basePath: "./cartridges",
    }),
  ],
})
```

```js
// resolves first match in cartridge path
const foo = require("*/cartridge/scripts/foo")

// resolves inside the caller's own cartridge
const bar = require("~/cartridge/scripts/bar")

// resolves to next cartridge in path — rewritten to a static import
const base = module.superModule
```

## Why this plugin exists

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.

This plugin resolves those patterns according to cartridge path order and rewrites source code so Vite can process the full module graph.

## Choosing the right package

Use this plugin when a Vite-based tool needs cartridge-aware module resolution without an SFCC test runtime.

Use [`@commerce-klaus/vitest-sfcc`](../vitest-sfcc/) when cartridge code must run in Vitest. It adds the CommonJS transformation, `dw/*` and `server` implementations, globals, dependency mocking, hooks, and controller and job-step harnesses needed for tests. It already performs cartridge resolution, so the two plugins should not be configured together in the same Vitest run.

## Features

* Resolves `require("*/...")` against the configured cartridge path in order.
* Resolves `require("~/...")` against the caller's own cartridge.
* Resolves `module.superModule` to the next cartridge implementation.
* Supports `.js`, `.ds`, and `.json` file extensions.
* Works in Vite and Vitest pipelines.

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @commerce-klaus/vite-plugin-sfcc-modules
```

```bash [yarn]
yarn add -D @commerce-klaus/vite-plugin-sfcc-modules
```

```bash [npm]
npm install -D @commerce-klaus/vite-plugin-sfcc-modules
```

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

:::

## Usage

Add the plugin to your Vite config:

```ts{2,5-9} [vite.config.ts]
import { defineConfig } from "vite"
import sfccModules from "@commerce-klaus/vite-plugin-sfcc-modules"

export default defineConfig({
  plugins: [
    sfccModules({
      cartridgePath: ["app_brand", "app_core", "app_storefront_base"],
      basePath: "./cartridges",
    }),
  ],
})
```

Example with cartridge order inferred from site template (`sites/<site>/site.xml`):

```ts{2,5-9} [vite.config.ts]
import { defineConfig } from "vite"
import sfccModules from "@commerce-klaus/vite-plugin-sfcc-modules"

export default defineConfig({
  plugins: [
    sfccModules({
      basePath: "./cartridges",
      siteTemplatePath: "./sites/site_template",
      site: "RefArch",
    }),
  ],
})
```

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

```ts{2,5-8} [vite.config.ts]
import { defineConfig } from "vite"
import sfccModules from "@commerce-klaus/vite-plugin-sfcc-modules"

export default defineConfig({
  plugins: [
    sfccModules({
      basePath: "./cartridges",
      envCartridgePath: "app_brand:app_core:app_storefront_base",
    }),
  ],
})
```

### Options

| Option               | Type              | Required | Description                                                                         |
| -------------------- | ----------------- | -------- | ----------------------------------------------------------------------------------- |
| `cartridgePath`      | `string[]`        | no       | Ordered cartridge lookup path. First match wins.                                    |
| `basePath`           | `string`          | no       | Cartridge directory override. Defaults to central config, then `cartridges`.        |
| `cwd`                | `string`          | no       | Working directory used to resolve relative paths.                                   |
| `siteTemplatePath`   | `string`          | no       | Site-template root that contains `sites/<site>/site.xml`.                           |
| `site`               | `string`          | no       | Site identifier used to read `custom-cartridges` from `site.xml`.                   |
| `solutionConfigPath` | `string`          | no       | Path to `cartridges/jsconfig.json` for reference-based cartridge order.             |
| `envCartridgePath`   | `string`          | no       | Cartridge order as a colon-separated string (same format as `SFCC_CARTRIDGE_PATH`). |
| `configFile`         | `string \| false` | no       | 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 `cartridgePath` order and picks the first matching file.

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

Resolves only in the current file's cartridge.

### 3. `module.superModule`

Resolves to the next matching module in cartridge path order after the current cartridge.

Important: `module.superModule` is rewritten to a static `import`, not a runtime `require()`. This is intentional so Vite can transform transitive super-module chains as part of the normal module graph.

## Vite + Vitest notes

* Use the plugin in the top-level `plugins` array of `vite.config.ts`.
* Do not rely on test-only plugin wiring that skips transitive transforms.
* In tests, prefer static `import` over `createRequire`, since `createRequire` bypasses Vite transforms.

## Relationship to @commerce-klaus/babel-plugin-sfcc-modules

| Topic                | `@commerce-klaus/babel-plugin-sfcc-modules` | `@commerce-klaus/vite-plugin-sfcc-modules` |
| -------------------- | ------------------------------------------- | ------------------------------------------ |
| Transformation layer | Babel                                       | Vite transform pipeline                    |
| Runtime setup        | Often Babel tooling / register              | Native Vite/Vitest                         |
| Main use case        | Babel-based SFCC toolchains                 | Modern Vite-based SFCC toolchains          |

## 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/vite-plugin-sfcc-modules

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

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