Getting started

Commerce Klaus is a set of focused packages. Adopt only the parts your project needs, or combine them into one consistent SFCC development workflow.

Requirements

• Node.js 22.13 or newer
• An SFCC cartridge project
• Vite+, pnpm, Yarn, or npm

Recommended setup

Start with static runtime checks and cartridge-aware types:

pnpm

pnpm add -D eslint typescript @salesforce/b2c-cli \
  @commerce-klaus/eslint-config-sfcc \
  @commerce-klaus/typescript-sfcc

yarn

yarn add -D eslint typescript @salesforce/b2c-cli \
  @commerce-klaus/eslint-config-sfcc \
  @commerce-klaus/typescript-sfcc

npm

npm install -D eslint typescript @salesforce/b2c-cli \
  @commerce-klaus/eslint-config-sfcc \
  @commerce-klaus/typescript-sfcc

Vite+

vp install -D eslint typescript @salesforce/b2c-cli \
  @commerce-klaus/eslint-config-sfcc \
  @commerce-klaus/typescript-sfcc

Add the recommended ESLint flat config:

eslint.config.js

import { defineConfig } from "eslint/config"
import sfcc from "@commerce-klaus/eslint-config-sfcc"

export default defineConfig(sfcc.configs.recommended)

For a faster lint path, Commerce Klaus also exposes its supported SFCC and SiteGenesis rules through Oxlint's JavaScript plugin API:

pnpm

pnpm add -D oxlint @commerce-klaus/eslint-config-sfcc

yarn

yarn add -D oxlint @commerce-klaus/eslint-config-sfcc

npm

npm install -D oxlint @commerce-klaus/eslint-config-sfcc

Vite+

vp install -D oxlint @commerce-klaus/eslint-config-sfcc

oxlint.config.mjs

import sfcc from "@commerce-klaus/eslint-config-sfcc/configs/oxlint"

export default sfcc

Oxlint cannot run the three rules whose input is invalid JavaScript syntax. Projects that need those checks can follow Oxlint with the minimal ESLint fallback instead of running the complete ESLint preset twice.

Enable cartridge-aware TypeScript resolution:

cartridges/jsconfig.json

{
  "compilerOptions": {
    "plugins": [{ "name": "@commerce-klaus/typescript-sfcc" }]
  }
}

Synchronize Salesforce types and check the cartridges:

pnpm

pnpm exec sfcc-ts-sync-types
pnpm exec sfcc-ts-typecheck

yarn

yarn exec sfcc-ts-sync-types
yarn exec sfcc-ts-typecheck

npm

npm exec -- sfcc-ts-sync-types
npm exec -- sfcc-ts-typecheck

Vite+

vp exec sfcc-ts-sync-types
vp exec sfcc-ts-typecheck

To run the same operations through the Salesforce B2C CLI, add the Commerce Klaus plugin as a development dependency:

pnpm

pnpm add -D @commerce-klaus/b2c-plugin @salesforce/b2c-cli

yarn

yarn add -D @commerce-klaus/b2c-plugin @salesforce/b2c-cli

npm

npm install -D @commerce-klaus/b2c-plugin @salesforce/b2c-cli

Vite+

vp install -D @commerce-klaus/b2c-plugin @salesforce/b2c-cli

Register the project-local plugin after dependency installation:

package.json

{
  "scripts": {
    "prepare": "b2c plugins link node_modules/@commerce-klaus/b2c-plugin --no-install"
  }
}

The package manager runs prepare during installation. Then use the plugin commands in project scripts or invoke them directly:

pnpm

pnpm exec b2c klaus types sync
pnpm exec b2c klaus types check

yarn

yarn exec b2c klaus types sync
yarn exec b2c klaus types check

npm

npm exec -- b2c klaus types sync
npm exec -- b2c klaus types check

Vite+

vp exec b2c klaus types sync
vp exec b2c klaus types check

Keep the standalone sfcc-ts-* commands for project-local scripts and CI when plugin installation state should not be shared outside the lockfile.

Add SFCC-aware unit tests

Use the dedicated Vitest integration when tests need to execute cartridge code:

pnpm

pnpm add -D vitest @commerce-klaus/vitest-sfcc

yarn

yarn add -D vitest @commerce-klaus/vitest-sfcc

npm

npm install -D vitest @commerce-klaus/vitest-sfcc

Vite+

vp install -D vitest @commerce-klaus/vitest-sfcc

Configure the same cartridge path used by the application:

vitest.config.ts

import sfccVitest from "@commerce-klaus/vitest-sfcc"
import { defineConfig } from "vitest/config"

export default defineConfig({
  plugins: [
    sfccVitest({
      basePath: "./cartridges",
      cartridgePath: ["app_custom", "app_storefront_base"],
    }),
  ],
})

The plugin loads CommonJS cartridge modules with SFCC-aware resolution and provides controlled platform modules, globals, dependency mocks, and harnesses for controllers, hooks, and job steps. See the Vitest integration guide for runtime setup and test examples.

Add local module resolution

Choose the adapter that matches the tool running your server-side code:

• Use the Vitest plugin for unit tests that execute cartridge code.
• Use the Vite plugin when another Vite-based tool needs cartridge-aware module resolution without the test runtime.
• Use the Babel plugin for existing Babel-based tests and tooling.

These integrations use the same resolver core, so */, ~/, cartridge aliases, and module.superModule follow the same ordering rules. Do not configure the Vite and Vitest plugins together; the Vitest package already includes the required module resolution.

Complete example

See the ESLint, TypeScript, and Vitest SFCC example for a runnable two-cartridge setup. It demonstrates a shared cartridge path loaded from the site template, generated SFCC types, custom attributes, hooks, a Custom API, cartridge overrides, and the SFCC-aware Vitest runtime.

For a smaller Vite+ setup, see the Oxlint and ESLint SFCC example. It runs the Oxlint-compatible SFCC rules through Vite+ and follows them with the minimal ESLint fallback while using the same TypeScript and Vite module resolution.

Next step

Choose the packages for your workflow →