Commerce Klaus

NPM version Downloads

@commerce-klaus/b2c-plugin ​

Run Commerce Klaus development tools through the Salesforce B2C CLI.

The plugin is a thin command adapter. Type checking and generated declarations remain implemented by @commerce-klaus/typescript-sfcc; cartridge discovery, metadata inspection, and SFCC module resolution remain implemented by @commerce-klaus/sfcc-module-resolver. The TypeScript package is a peer dependency so the editor plugin and B2C CLI commands always use the same compatible project-level version.

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.

All klaus project and type commands use the central configuration. Explicit CLI flags such as --cartridges-dir, --cartridge-path, --project, and --site-template-path override the corresponding shared values for one run.

Install ​

Install the B2C CLI and TypeScript tooling in the project, then register the project-local plugin during the package manager's prepare lifecycle:

bash
pnpm add -D @commerce-klaus/b2c-plugin @salesforce/b2c-cli @commerce-klaus/typescript-sfcc typescript
bash
npm install -D @commerce-klaus/b2c-plugin @salesforce/b2c-cli @commerce-klaus/typescript-sfcc typescript
bash
yarn add -D @commerce-klaus/b2c-plugin @salesforce/b2c-cli @commerce-klaus/typescript-sfcc typescript
bash
vp install -D @commerce-klaus/b2c-plugin @salesforce/b2c-cli @commerce-klaus/typescript-sfcc typescript
package.json
json
{
  "scripts": {
    "prepare": "b2c plugins link node_modules/@commerce-klaus/b2c-plugin --no-install"
  }
}

The package manager runs prepare after dependency installation. When the linked plugin changes without an install, run the script manually:

bash
pnpm run prepare
bash
npm run prepare
bash
yarn run prepare
bash
vp run prepare

Confirm that the plugin is available:

bash
pnpm exec b2c plugins
bash
npm exec -- b2c plugins
bash
yarn exec b2c plugins
bash
vp exec b2c plugins

Synchronize types ​

Synchronize Salesforce Script API declarations and generate project-specific types for custom attributes, hooks, Custom APIs, and job steps:

bash
pnpm exec b2c klaus types sync
bash
npm exec -- b2c klaus types sync
bash
yarn exec b2c klaus types sync
bash
vp exec b2c klaus types sync

Available options:

text
--force
--min-version <version>
--output <path>
--site-template-path <path>
--project-directory <path>

The command delegates Salesforce declaration generation to b2c setup ide vscode-types before generating the Commerce Klaus declarations.

Check type status ​

Check Salesforce Script API types and generated project declarations without changing files:

bash
pnpm exec b2c klaus types status --min-version 26.7.0
bash
npm exec -- b2c klaus types status --min-version 26.7.0
bash
yarn exec b2c klaus types status --min-version 26.7.0
bash
vp exec b2c klaus types status --min-version 26.7.0

The command renders the declarations expected from the current metadata in memory and compares them with .b2c-script-types/types. It reports each output as current, missing, stale, or not required. Exit code 2 means synchronization is required; exit code 1 indicates a runtime or configuration error.

Clean generated types ​

Remove the project-specific declarations generated by Commerce Klaus:

bash
pnpm exec b2c klaus types clean --dry-run
bash
npm exec -- b2c klaus types clean --dry-run
bash
yarn exec b2c klaus types clean --dry-run
bash
vp exec b2c klaus types clean --dry-run

Remove --dry-run to delete the files. The command only manages sfcc-*.generated.d.ts outputs created by Commerce Klaus. It preserves the Salesforce Script API declarations and any other files in .b2c-script-types/types.

Typecheck cartridges ​

Run the cartridge-aware TypeScript checker:

bash
pnpm exec b2c klaus types check
bash
npm exec -- b2c klaus types check
bash
yarn exec b2c klaus types check
bash
vp exec b2c klaus types check

By default, the command searches from the current directory upward for cartridges/jsconfig.json. Explicit paths are also supported:

bash
pnpm exec b2c klaus types check \
  --project cartridges/tsconfig.json \
  --cartridges-dir cartridges
bash
npm exec -- b2c klaus types check \
  --project cartridges/tsconfig.json \
  --cartridges-dir cartridges
bash
yarn exec b2c klaus types check \
  --project cartridges/tsconfig.json \
  --cartridges-dir cartridges
bash
vp exec b2c klaus types check \
  --project cartridges/tsconfig.json \
  --cartridges-dir cartridges

Use --project-directory <path> when invoking the command outside the project root. --working-directory is accepted as an alias.

All four type commands support B2C CLI's standard --json flag for automation:

bash
pnpm exec b2c klaus types check --json
pnpm exec b2c klaus types clean --json
pnpm exec b2c klaus types sync --json
pnpm exec b2c klaus types status --json
bash
npm exec -- b2c klaus types check --json
npm exec -- b2c klaus types clean --json
npm exec -- b2c klaus types sync --json
npm exec -- b2c klaus types status --json
bash
yarn exec b2c klaus types check --json
yarn exec b2c klaus types clean --json
yarn exec b2c klaus types sync --json
yarn exec b2c klaus types status --json
bash
vp exec b2c klaus types check --json
vp exec b2c klaus types clean --json
vp exec b2c klaus types sync --json
vp exec b2c klaus types status --json

Inspect and diagnose a project ​

Show the effective cartridge order and resolved hooks, job steps, and Custom APIs:

bash
pnpm exec b2c klaus inspect --json
bash
npm exec -- b2c klaus inspect --json
bash
yarn exec b2c klaus inspect --json
bash
vp exec b2c klaus inspect --json

Check that the cartridges directory and configured cartridges exist:

bash
pnpm exec b2c klaus doctor --cartridge-path app_custom:app_storefront_base
bash
npm exec -- b2c klaus doctor --cartridge-path app_custom:app_storefront_base
bash
yarn exec b2c klaus doctor --cartridge-path app_custom:app_storefront_base
bash
vp exec b2c klaus doctor --cartridge-path app_custom:app_storefront_base

Warnings do not fail the command. Configuration errors produce a non-zero exit status, making doctor suitable for CI.

Visualize project relationships ​

Create a graph of cartridge precedence, module.superModule chains, SFRA controller routes and their effective middleware order, hook and job step implementations, and Custom API HTTP endpoints, schemas, and scripts:

bash
pnpm exec b2c klaus graph
pnpm exec b2c klaus graph --focus 'Product-Show'
pnpm exec b2c klaus graph --focus 'Product.js' --depth 2 --direction both
pnpm exec b2c klaus graph --cartridge-path app_base --diff app_custom:app_base
pnpm exec b2c klaus graph --module '*/cartridge/models/product'
pnpm exec b2c klaus graph --format dot --output sfcc-project.dot
pnpm exec b2c klaus graph --format mermaid --output sfcc-project.mmd
pnpm exec b2c klaus graph --format json --output sfcc-project.json
bash
npm exec -- b2c klaus graph
npm exec -- b2c klaus graph --focus 'Product-Show'
npm exec -- b2c klaus graph --focus 'Product.js' --depth 2 --direction both
npm exec -- b2c klaus graph --cartridge-path app_base --diff app_custom:app_base
npm exec -- b2c klaus graph --module '*/cartridge/models/product'
npm exec -- b2c klaus graph --format dot --output sfcc-project.dot
npm exec -- b2c klaus graph --format mermaid --output sfcc-project.mmd
npm exec -- b2c klaus graph --format json --output sfcc-project.json
bash
yarn exec b2c klaus graph
yarn exec b2c klaus graph --focus 'Product-Show'
yarn exec b2c klaus graph --focus 'Product.js' --depth 2 --direction both
yarn exec b2c klaus graph --cartridge-path app_base --diff app_custom:app_base
yarn exec b2c klaus graph --module '*/cartridge/models/product'
yarn exec b2c klaus graph --format dot --output sfcc-project.dot
yarn exec b2c klaus graph --format mermaid --output sfcc-project.mmd
yarn exec b2c klaus graph --format json --output sfcc-project.json
bash
vp exec b2c klaus graph
vp exec b2c klaus graph --focus 'Product-Show'
vp exec b2c klaus graph --focus 'Product.js' --depth 2 --direction both
vp exec b2c klaus graph --cartridge-path app_base --diff app_custom:app_base
vp exec b2c klaus graph --module '*/cartridge/models/product'
vp exec b2c klaus graph --format dot --output sfcc-project.dot
vp exec b2c klaus graph --format mermaid --output sfcc-project.mmd
vp exec b2c klaus graph --format json --output sfcc-project.json

The default output is a concise, colored relationship list. --format dot emits Graphviz DOT without decorative output, while --format mermaid emits a left-to-right Mermaid flowchart suitable for Markdown and documentation. --json returns the same nodes and typed edges as structured data. --module accepts the */cartridge/... form and limits module discovery to that path. --focus matches node IDs, labels, and paths case-insensitively and follows outgoing dependencies by default. --direction dependents follows incoming relationships instead, while --direction both traverses in both directions. Use --depth <number> to limit the number of traversed relationships. A depth of zero returns only matching nodes. --focus and --module are mutually exclusive. --diff <cartridge-path> compares the effective graph for the regular --cartridge-path baseline with another cartridge path. The result separates added, removed, and changed nodes and relationships. Comparisons support text and JSON output; DOT and Mermaid are reserved for individual graphs. --output (short form -o) writes text, DOT, Mermaid, or JSON directly to a file and creates missing parent directories. Use --format json --output <path> for a JSON artifact; the standard --json flag remains reserved for structured stdout.

Generated example ​

This graph is generated during every documentation build from the repository's anonymous app_custom:app_example consumer project. It exercises cartridge precedence, an inherited SFRA Product controller with prepended, appended, and replaced routes, the resulting route pipelines, other Super Modules, hooks, a job step, and a Custom API schema and implementation using the current graph resolver and Mermaid renderer. The Custom API flow starts at its OAS method and path before reaching the operation, implementation script, and schema.

  • Cartridge
  • Module
  • Hook
  • HTTP endpoint
  • Job step
  • Middleware
  • Custom API
  • SFRA route
  • Schema

Analyze file impact ​

Find the SFCC processes connected to a changed project file:

bash
pnpm exec b2c klaus impact cartridges/app_custom/cartridge/controllers/Product.js
pnpm exec b2c klaus impact cartridges/app_custom/cartridge/scripts/hooks/order.js --depth 2
bash
npm exec -- b2c klaus impact cartridges/app_custom/cartridge/controllers/Product.js
npm exec -- b2c klaus impact cartridges/app_custom/cartridge/scripts/hooks/order.js --depth 2
bash
yarn exec b2c klaus impact cartridges/app_custom/cartridge/controllers/Product.js
yarn exec b2c klaus impact cartridges/app_custom/cartridge/scripts/hooks/order.js --depth 2
bash
vp exec b2c klaus impact cartridges/app_custom/cartridge/controllers/Product.js
vp exec b2c klaus impact cartridges/app_custom/cartridge/scripts/hooks/order.js --depth 2

The command resolves the file from the current working directory and traverses its project graph relationships in both directions. The result includes affected SFRA routes and middleware, hooks, job steps, Custom APIs, schemas, and Super Modules represented in the graph. Use --depth <number> to limit the traversal or --json for structured output. A missing file or a file without known project graph relationships produces an explicit error.

Validate project contracts ​

Validate hook registrations, job step definitions, and Custom API contracts:

bash
pnpm exec b2c klaus validate
pnpm exec b2c klaus validate --watch
pnpm exec b2c klaus validate --format sarif > sfcc-validation.sarif
bash
npm exec -- b2c klaus validate
npm exec -- b2c klaus validate --watch
npm exec -- b2c klaus validate --format sarif > sfcc-validation.sarif
bash
yarn exec b2c klaus validate
yarn exec b2c klaus validate --watch
yarn exec b2c klaus validate --format sarif > sfcc-validation.sarif
bash
vp exec b2c klaus validate
vp exec b2c klaus validate --watch
vp exec b2c klaus validate --format sarif > sfcc-validation.sarif

Missing scripts, modules, schemas, and OAS operations are reported as errors. Hook and job step registrations hidden by an earlier cartridge are reported as warnings. Errors produce a non-zero exit status. Use --json to receive stable diagnostic codes, severities, source files, and summary counts for automation. Use --watch (short form -w) during development to rerun validation after changes to .js, .ds, .json, .yaml, or .yml files under the cartridges directory. Rapid file events are combined into one validation run. Watch mode uses human-readable output and cannot be combined with --json or --format sarif.

Use --format sarif to emit a SARIF 2.1.0 report for GitHub Code Scanning, VS Code, and other compatible CI tools. Each result contains the stable diagnostic code as its rule ID, its severity and message, and a project-relative source URI. Upload sfcc-validation.sarif with github/codeql-action/upload-sarif to display contract findings directly on a pull request. SARIF output cannot be combined with the standard --json flag.

Resolve a module ​

Resolve an SFCC module and show all wildcard candidates in cartridge-path order:

bash
pnpm exec b2c klaus resolve '*/cartridge/scripts/example'
bash
npm exec -- b2c klaus resolve '*/cartridge/scripts/example'
bash
yarn exec b2c klaus resolve '*/cartridge/scripts/example'
bash
vp exec b2c klaus resolve '*/cartridge/scripts/example'

For a ~/ module, provide the importing file with --from. All project commands accept --cartridges-dir, --cartridge-path, and the standard --json flag where applicable.

Explain module resolution ​

Show every path Commerce Klaus checks before resolving a module:

bash
pnpm exec b2c klaus explain '*/cartridge/scripts/example'
pnpm exec b2c klaus explain module.superModule --from cartridges/app_custom/cartridge/controllers/Page.js
bash
npm exec -- b2c klaus explain '*/cartridge/scripts/example'
npm exec -- b2c klaus explain module.superModule --from cartridges/app_custom/cartridge/controllers/Page.js
bash
yarn exec b2c klaus explain '*/cartridge/scripts/example'
yarn exec b2c klaus explain module.superModule --from cartridges/app_custom/cartridge/controllers/Page.js
bash
vp exec b2c klaus explain '*/cartridge/scripts/example'
vp exec b2c klaus explain module.superModule --from cartridges/app_custom/cartridge/controllers/Page.js

The trace reports the resolution mode, importer and containing cartridge, effective cartridge order, the source that selected that order, and each exact file candidate as MISS or MATCH. Order sources include explicit configuration, environment variables, solution jsconfig references, site templates, and the deterministic filesystem fallback. Missing configured cartridges and invalid solution configurations are shown before module lookup, so an unexpected fallback is visible immediately.

Candidate lookup includes extensionless files, .js, .ds, .json, declaration files, and directory index candidates in their actual order. ~/ and module.superModule require --from; the latter starts searching only after the importing cartridge. Use --json for the complete structured module and cartridge-order traces.

Explain Custom API resolution ​

Show which api.json registration wins for one Custom API operation:

bash
pnpm exec b2c klaus explain custom-api basket-preparation prepareBasket
bash
npm exec -- b2c klaus explain custom-api basket-preparation prepareBasket
bash
yarn exec b2c klaus explain custom-api basket-preparation prepareBasket
bash
vp exec b2c klaus explain custom-api basket-preparation prepareBasket

The trace uses the effective project cartridge path and marks every cartridge as SELECT, SHADOWED, or MISS. Matching registrations include their api.json, OAS schema, HTTP method and path, and resolved implementation script. The cartridge-order source is shown as well, so configuration, environment, solution, site-template, and filesystem fallbacks remain visible. A selected registration with a missing OAS operation or implementation is reported as incomplete instead of looking successful.

Use --cartridges-dir or --cartridge-path to inspect a different project layout or precedence order. Use --json for the complete structured trace, including all attempted cartridges and shadowed registrations.

Explain hook resolution ​

Show which hooks.json registration provides one extension point:

bash
pnpm exec b2c klaus explain hook app.payment.authorize
bash
npm exec -- b2c klaus explain hook app.payment.authorize
bash
yarn exec b2c klaus explain hook app.payment.authorize
bash
vp exec b2c klaus explain hook app.payment.authorize

Each cartridge is marked as SELECT, SHADOWED, UNRESOLVED, INVALID, or MISS. Matching registrations include the declaring hooks.json, configured script, and resolved implementation. An unresolved script does not block a valid lower-precedence registration, matching the runtime resolver.

Explain job step resolution ​

Show which steptypes.json definition provides one job step type:

bash
pnpm exec b2c klaus explain job-step custom.ExportProducts
bash
npm exec -- b2c klaus explain job-step custom.ExportProducts
bash
yarn exec b2c klaus explain job-step custom.ExportProducts
bash
vp exec b2c klaus explain job-step custom.ExportProducts

The trace shows the selected, shadowed, unresolved, invalid, and missing definitions in cartridge order. A resolved definition includes its task or chunk kind, module and implementation, parameter and status-code counts, configured task function and timeout, or chunk size and lifecycle functions. Invalid documents retain their parser diagnostics and JSON paths.

Both metadata commands show cartridge-order provenance and support --cartridges-dir, --cartridge-path, and --json.

Standalone commands ​

The original project-local commands remain available:

bash
pnpm exec sfcc-ts-sync-types
pnpm exec sfcc-ts-typecheck
bash
npm exec -- sfcc-ts-sync-types
npm exec -- sfcc-ts-typecheck
bash
yarn exec sfcc-ts-sync-types
yarn exec sfcc-ts-typecheck
bash
vp exec sfcc-ts-sync-types
vp exec sfcc-ts-typecheck

They are useful in CI environments where every executable must be represented directly by the project lockfile rather than an installed B2C CLI plugin.

Released under the MIT License.

Commerce Klaus