@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 projects often use module patterns that are not standard Node.js resolution:

• require("*/cartridge/scripts/foo")
• require("~/cartridge/scripts/bar")
• module.superModule

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

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

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	yes	Path to the cartridges directory. Resolved relative to cwd (or process.cwd()).
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).

If cartridgePath is omitted, cartridge order is inferred with this precedence:

1. envCartridgePath (or SFCC_CARTRIDGE_PATH)
2. solutionConfigPath references
3. siteTemplatePath + site (custom-cartridges in site.xml)
4. filesystem fallback (alphabetical)

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