@commerce-klaus/sfcc-module-resolver
Shared Node.js utilities for SFCC cartridge order, module resolution, super modules, and hook registrations. Most projects use it indirectly through the Commerce Klaus ESLint, TypeScript, Vite, or Babel packages.
Highlights
- Infers cartridge order from configuration, environment,
jsconfig, orsite.xml - Explains which cartridge-order source won, including missing entries and invalid fallbacks
- Resolves
*/,~/, cartridge aliases, andmodule.superModule - Explains resolution with every attempted file path and the selected match
- Provides deterministic filesystem helpers for SFCC-aware tooling
- Normalizes Custom Attribute and preference definitions from site metadata
- Reads and resolves cartridge hook registrations
- Discovers effective hook scripts in cartridge-path order
- Reads job step definitions, parameters, status codes, execution capabilities, and task timeouts from
steptypes.json - Validates hook, job step, and Custom API contracts with structured diagnostics
- Builds deterministic project graphs for cartridge precedence, super modules, SFRA controller routes, effective middleware pipelines, and metadata contracts
ModuleResolutionOptions is the shared configuration type used by the Vite
and Vitest adapters. ResolveCartridgeRootsOptions extends it with the
resolver-only containingFile option.
Projects can put shared options in commerce-klaus.config.ts or
commerce-klaus.config.js. Package options remain supported and override the
central values. The public configuration contract lives in
@commerce-klaus/config; see the project configuration guide.
Install
pnpm add @commerce-klaus/sfcc-module-resolver
npm install @commerce-klaus/sfcc-module-resolver
yarn add @commerce-klaus/sfcc-module-resolver
vp install @commerce-klaus/sfcc-module-resolver
import {
createModuleResolver,
explainCartridgeOrder,
inferCartridgeOrder,
} from "@commerce-klaus/sfcc-module-resolver/resolution"
const cartridgeRoots = inferCartridgeOrder({ cartridgesDir: "cartridges" })
const resolveSfccModule = createModuleResolver(cartridgeRoots)
const orderTrace = explainCartridgeOrder({ cartridgesDir: "cartridges" })
The package provides focused entry points for resolution, object-metadata,
hooks, job-steps, custom-apis, and project-wide validation and graphs under
project. The package root contains the resolution API only.
Documentation
See the complete API and resolution reference.
License
MIT