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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jens Simon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+[![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
+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 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
+
+```bash
+pnpm add -D @commerce-klaus/vite-plugin-sfcc-modules
+```
+
+or
+
+```bash
+npm i -D @commerce-klaus/vite-plugin-sfcc-modules
+```
+
+or
+
+```bash
+yarn add -D @commerce-klaus/vite-plugin-sfcc-modules
+```
+
+## Usage
+
+Add the plugin to your 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",
+    }),
+  ],
+})
+```
+
+### Options
+
+| Option          | Type       | Required | Description                                                                                        |
+| --------------- | ---------- | -------- | -------------------------------------------------------------------------------------------------- |
+| `cartridgePath` | `string[]` | yes      | Ordered cartridge lookup path. First match wins.                                                   |
+| `basePath`      | `string`   | yes      | Path to the folder containing cartridges in `cartridgePath`. Resolved relative to `process.cwd()`. |
+
+## 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-olugin-sfcc-modules
+[npm-image]: https://badgen.net/npm/v/@commerce-klaus/vite-olugin-sfcc-modules
+[npm-downloads-image]: https://badgen.net/npm/dw/@commerce-klaus/vite-olugin-sfcc-modules

package/dist/index.cjs

@@ -0,0 +1,105 @@
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let node_fs = require("node:fs");
+node_fs = __toESM(node_fs, 1);
+let node_path = require("node:path");
+node_path = __toESM(node_path, 1);
+//#region src/index.ts
+const EXTENSIONS = [
+	"js",
+	"ds",
+	"json"
+];
+/**
+* Finds the first existing file for a target module path across cartridges.
+*
+* The function tries all supported extensions in cartridgePath order.
+*/
+function findFirst(basePath, cartridges, target) {
+	for (const cartridge of cartridges) for (const ext of EXTENSIONS) {
+		const full = node_path.default.join(basePath, cartridge, `${target}.${ext}`);
+		if (node_fs.default.existsSync(full)) return full;
+	}
+}
+/** Removes only the trailing file extension from a path string. */
+function stripExt(p) {
+	return p.replace(/\.[^.]+$/, "");
+}
+/**
+* Vite plugin to resolve SFCC-specific module patterns.
+*
+* Supported patterns:
+* - `require("<asterisk>/cartridge/...")` resolves against cartridgePath in order.
+* - `require("~/cartridge/...")` resolves in the importer's own cartridge.
+* - `module.superModule` resolves to the next matching module in cartridgePath.
+*
+* module.superModule is rewritten to a static import so Vite can transform
+* transitive super modules as part of the normal module graph.
+*/
+function sfccModules({ cartridgePath, basePath: rawBasePath }) {
+	const basePath = node_path.default.resolve(rawBasePath);
+	return {
+		name: "vite-plugin-sfcc-modules",
+		resolveId(source, importer) {
+			if (source.startsWith("*/")) {
+				const found = findFirst(basePath, cartridgePath, source.slice(2));
+				if (found) return found;
+			}
+			if (source.startsWith("~/") && importer) {
+				const ownCartridge = node_path.default.relative(basePath, importer).split(node_path.default.sep)[0];
+				if (ownCartridge) {
+					const found = findFirst(basePath, [ownCartridge], source.slice(2));
+					if (found) return found;
+				}
+			}
+		},
+		transform(code, id) {
+			const parts = node_path.default.relative(basePath, id).split(node_path.default.sep);
+			const ownCartridge = parts[0];
+			const isInCartridge = ownCartridge && cartridgePath.includes(ownCartridge);
+			let transformed = code;
+			transformed = transformed.replace(/require\((['"])\*\/([^'"]+)\1\)/g, (_match, _quote, target) => {
+				const found = findFirst(basePath, cartridgePath, `/${target}`);
+				return found ? `require(${JSON.stringify(found)})` : _match;
+			});
+			if (isInCartridge) transformed = transformed.replace(/require\((['"])~\/([^'"]+)\1\)/g, (_match, _quote, target) => {
+				const found = findFirst(basePath, [ownCartridge], `/${target}`);
+				return found ? `require(${JSON.stringify(found)})` : _match;
+			});
+			if (isInCartridge && transformed.includes("module.superModule")) {
+				const modulePathWithoutExt = "/" + stripExt(parts.slice(1).join("/"));
+				const ownIndex = cartridgePath.indexOf(ownCartridge);
+				const found = findFirst(basePath, cartridgePath.slice(ownIndex + 1), modulePathWithoutExt);
+				if (found) transformed = `import __sfcc_superModule__ from ${JSON.stringify(found)}\n` + transformed.replace(/\bmodule\.superModule\b/g, "__sfcc_superModule__");
+				else transformed = transformed.replace(/\bmodule\.superModule\b/g, "undefined");
+			}
+			if (transformed === code) return null;
+			return {
+				code: transformed,
+				map: null
+			};
+		}
+	};
+}
+//#endregion
+module.exports = sfccModules;

package/dist/index.mjs

@@ -0,0 +1,81 @@
+import fs from "node:fs";
+import path from "node:path";
+//#region src/index.ts
+const EXTENSIONS = [
+	"js",
+	"ds",
+	"json"
+];
+/**
+* Finds the first existing file for a target module path across cartridges.
+*
+* The function tries all supported extensions in cartridgePath order.
+*/
+function findFirst(basePath, cartridges, target) {
+	for (const cartridge of cartridges) for (const ext of EXTENSIONS) {
+		const full = path.join(basePath, cartridge, `${target}.${ext}`);
+		if (fs.existsSync(full)) return full;
+	}
+}
+/** Removes only the trailing file extension from a path string. */
+function stripExt(p) {
+	return p.replace(/\.[^.]+$/, "");
+}
+/**
+* Vite plugin to resolve SFCC-specific module patterns.
+*
+* Supported patterns:
+* - `require("<asterisk>/cartridge/...")` resolves against cartridgePath in order.
+* - `require("~/cartridge/...")` resolves in the importer's own cartridge.
+* - `module.superModule` resolves to the next matching module in cartridgePath.
+*
+* module.superModule is rewritten to a static import so Vite can transform
+* transitive super modules as part of the normal module graph.
+*/
+function sfccModules({ cartridgePath, basePath: rawBasePath }) {
+	const basePath = path.resolve(rawBasePath);
+	return {
+		name: "vite-plugin-sfcc-modules",
+		resolveId(source, importer) {
+			if (source.startsWith("*/")) {
+				const found = findFirst(basePath, cartridgePath, source.slice(2));
+				if (found) return found;
+			}
+			if (source.startsWith("~/") && importer) {
+				const ownCartridge = path.relative(basePath, importer).split(path.sep)[0];
+				if (ownCartridge) {
+					const found = findFirst(basePath, [ownCartridge], source.slice(2));
+					if (found) return found;
+				}
+			}
+		},
+		transform(code, id) {
+			const parts = path.relative(basePath, id).split(path.sep);
+			const ownCartridge = parts[0];
+			const isInCartridge = ownCartridge && cartridgePath.includes(ownCartridge);
+			let transformed = code;
+			transformed = transformed.replace(/require\((['"])\*\/([^'"]+)\1\)/g, (_match, _quote, target) => {
+				const found = findFirst(basePath, cartridgePath, `/${target}`);
+				return found ? `require(${JSON.stringify(found)})` : _match;
+			});
+			if (isInCartridge) transformed = transformed.replace(/require\((['"])~\/([^'"]+)\1\)/g, (_match, _quote, target) => {
+				const found = findFirst(basePath, [ownCartridge], `/${target}`);
+				return found ? `require(${JSON.stringify(found)})` : _match;
+			});
+			if (isInCartridge && transformed.includes("module.superModule")) {
+				const modulePathWithoutExt = "/" + stripExt(parts.slice(1).join("/"));
+				const ownIndex = cartridgePath.indexOf(ownCartridge);
+				const found = findFirst(basePath, cartridgePath.slice(ownIndex + 1), modulePathWithoutExt);
+				if (found) transformed = `import __sfcc_superModule__ from ${JSON.stringify(found)}\n` + transformed.replace(/\bmodule\.superModule\b/g, "__sfcc_superModule__");
+				else transformed = transformed.replace(/\bmodule\.superModule\b/g, "undefined");
+			}
+			if (transformed === code) return null;
+			return {
+				code: transformed,
+				map: null
+			};
+		}
+	};
+}
+//#endregion
+export { sfccModules as default };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@commerce-klaus/vite-plugin-sfcc-modules",
+  "version": "0.0.0",
+  "description": "Vite plugin to handle non-standard module paths used by Salesforce Commerce Cloud (SFCC)",
+  "keywords": [
+    "cartridge",
+    "commercecloud",
+    "demandware",
+    "salesforce",
+    "sfcc",
+    "sfra",
+    "supermodule",
+    "vite",
+    "vite-plugin"
+  ],
+  "homepage": "https://github.com/commerce-klaus/commerce-klaus/tree/main/packages/vite-plugin-sfcc-modules#readme",
+  "bugs": {
+    "url": "https://github.com/commerce-klaus/commerce-klaus/issues"
+  },
+  "license": "MIT",
+  "author": "Jens Simon <https://github.com/jenssimon>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/commerce-klaus/commerce-klaus",
+    "directory": "packages/vite-plugin-sfcc-modules"
+  },
+  "files": [
+    "/dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp test",
+    "check": "vp check",
+    "prepublishOnly": "vp run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.0",
+    "@vitest/coverage-v8": "^4.1.5",
+    "typescript": "^6.0.0",
+    "vite-plus": "latest"
+  },
+  "peerDependencies": {
+    "vite": ">=5.0.0"
+  },
+  "packageManager": "pnpm@11.9.0"
+}