@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

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",
    }),
  ],
})

// 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 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.

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

pnpm

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

yarn

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

npm

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

Vite+

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

Usage

Add the plugin to your Vite config:

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):

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):

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):

vp install
vp check
vp test
vp run build

License

MIT