---
url: /commerce-klaus/packages/b2c-plugin.md
---
[![NPM version][npm-image]][npm-url] [![Downloads][npm-downloads-image]][npm-url]

# @commerce-klaus/b2c-plugin

Run Commerce Klaus development tools through the
[Salesforce B2C CLI](https://salesforcecommercecloud.github.io/b2c-developer-tooling/).

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](/guide/project-configuration).
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:

::: code-group

```bash [pnpm]
pnpm add -D @commerce-klaus/b2c-plugin @salesforce/b2c-cli @commerce-klaus/typescript-sfcc typescript
```

```bash [npm]
npm install -D @commerce-klaus/b2c-plugin @salesforce/b2c-cli @commerce-klaus/typescript-sfcc typescript
```

```bash [Yarn]
yarn add -D @commerce-klaus/b2c-plugin @salesforce/b2c-cli @commerce-klaus/typescript-sfcc typescript
```

```bash [Vite+]
vp install -D @commerce-klaus/b2c-plugin @salesforce/b2c-cli @commerce-klaus/typescript-sfcc typescript
```

:::

```json [package.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:

::: code-group

```bash [pnpm]
pnpm run prepare
```

```bash [npm]
npm run prepare
```

```bash [Yarn]
yarn run prepare
```

```bash [Vite+]
vp run prepare
```

:::

Confirm that the plugin is available:

::: code-group

```bash [pnpm]
pnpm exec b2c plugins
```

```bash [npm]
npm exec -- b2c plugins
```

```bash [Yarn]
yarn exec b2c plugins
```

```bash [Vite+]
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:

::: code-group

```bash [pnpm]
pnpm exec b2c klaus types sync
```

```bash [npm]
npm exec -- b2c klaus types sync
```

```bash [Yarn]
yarn exec b2c klaus types sync
```

```bash [Vite+]
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:

::: code-group

```bash [pnpm]
pnpm exec b2c klaus types status --min-version 26.7.0
```

```bash [npm]
npm exec -- b2c klaus types status --min-version 26.7.0
```

```bash [Yarn]
yarn exec b2c klaus types status --min-version 26.7.0
```

```bash [Vite+]
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:

::: code-group

```bash [pnpm]
pnpm exec b2c klaus types clean --dry-run
```

```bash [npm]
npm exec -- b2c klaus types clean --dry-run
```

```bash [Yarn]
yarn exec b2c klaus types clean --dry-run
```

```bash [Vite+]
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:

::: code-group

```bash [pnpm]
pnpm exec b2c klaus types check
```

```bash [npm]
npm exec -- b2c klaus types check
```

```bash [Yarn]
yarn exec b2c klaus types check
```

```bash [Vite+]
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:

::: code-group

```bash [pnpm]
pnpm exec b2c klaus types check \
  --project cartridges/tsconfig.json \
  --cartridges-dir cartridges
```

```bash [npm]
npm exec -- b2c klaus types check \
  --project cartridges/tsconfig.json \
  --cartridges-dir cartridges
```

```bash [Yarn]
yarn exec b2c klaus types check \
  --project cartridges/tsconfig.json \
  --cartridges-dir cartridges
```

```bash [Vite+]
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:

::: code-group

```bash [pnpm]
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]
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]
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 [Vite+]
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:

::: code-group

```bash [pnpm]
pnpm exec b2c klaus inspect --json
```

```bash [npm]
npm exec -- b2c klaus inspect --json
```

```bash [Yarn]
yarn exec b2c klaus inspect --json
```

```bash [Vite+]
vp exec b2c klaus inspect --json
```

:::

Check that the cartridges directory and configured cartridges exist:

::: code-group

```bash [pnpm]
pnpm exec b2c klaus doctor --cartridge-path app_custom:app_storefront_base
```

```bash [npm]
npm exec -- b2c klaus doctor --cartridge-path app_custom:app_storefront_base
```

```bash [Yarn]
yarn exec b2c klaus doctor --cartridge-path app_custom:app_storefront_base
```

```bash [Vite+]
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:

::: code-group

```bash [pnpm]
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]
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]
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 [Vite+]
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.

## Analyze file impact

Find the SFCC processes connected to a changed project file:

::: code-group

```bash [pnpm]
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]
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]
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 [Vite+]
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:

::: code-group

```bash [pnpm]
pnpm exec b2c klaus validate
pnpm exec b2c klaus validate --watch
pnpm exec b2c klaus validate --format sarif > sfcc-validation.sarif
```

```bash [npm]
npm exec -- b2c klaus validate
npm exec -- b2c klaus validate --watch
npm exec -- b2c klaus validate --format sarif > sfcc-validation.sarif
```

```bash [Yarn]
yarn exec b2c klaus validate
yarn exec b2c klaus validate --watch
yarn exec b2c klaus validate --format sarif > sfcc-validation.sarif
```

```bash [Vite+]
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:

::: code-group

```bash [pnpm]
pnpm exec b2c klaus resolve '*/cartridge/scripts/example'
```

```bash [npm]
npm exec -- b2c klaus resolve '*/cartridge/scripts/example'
```

```bash [Yarn]
yarn exec b2c klaus resolve '*/cartridge/scripts/example'
```

```bash [Vite+]
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:

::: code-group

```bash [pnpm]
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]
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]
yarn exec b2c klaus explain '*/cartridge/scripts/example'
yarn exec b2c klaus explain module.superModule --from cartridges/app_custom/cartridge/controllers/Page.js
```

```bash [Vite+]
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:

::: code-group

```bash [pnpm]
pnpm exec b2c klaus explain custom-api basket-preparation prepareBasket
```

```bash [npm]
npm exec -- b2c klaus explain custom-api basket-preparation prepareBasket
```

```bash [Yarn]
yarn exec b2c klaus explain custom-api basket-preparation prepareBasket
```

```bash [Vite+]
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:

::: code-group

```bash [pnpm]
pnpm exec b2c klaus explain hook app.payment.authorize
```

```bash [npm]
npm exec -- b2c klaus explain hook app.payment.authorize
```

```bash [Yarn]
yarn exec b2c klaus explain hook app.payment.authorize
```

```bash [Vite+]
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:

::: code-group

```bash [pnpm]
pnpm exec b2c klaus explain job-step custom.ExportProducts
```

```bash [npm]
npm exec -- b2c klaus explain job-step custom.ExportProducts
```

```bash [Yarn]
yarn exec b2c klaus explain job-step custom.ExportProducts
```

```bash [Vite+]
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:

::: code-group

```bash [pnpm]
pnpm exec sfcc-ts-sync-types
pnpm exec sfcc-ts-typecheck
```

```bash [npm]
npm exec -- sfcc-ts-sync-types
npm exec -- sfcc-ts-typecheck
```

```bash [Yarn]
yarn exec sfcc-ts-sync-types
yarn exec sfcc-ts-typecheck
```

```bash [Vite+]
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.

[npm-url]: https://www.npmjs.com/package/@commerce-klaus/b2c-plugin

[npm-image]: https://badgen.net/npm/v/@commerce-klaus/b2c-plugin

[npm-downloads-image]: https://badgen.net/npm/dw/@commerce-klaus/b2c-plugin