---
url: /commerce-klaus/guide/getting-started.md
---
# 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:

::: code-group

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

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

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

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

:::

Add the recommended ESLint flat config:

```js{2,4} [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:

::: code-group

```bash [pnpm]
pnpm add -D oxlint @commerce-klaus/eslint-config-sfcc
```

```bash [yarn]
yarn add -D oxlint @commerce-klaus/eslint-config-sfcc
```

```bash [npm]
npm install -D oxlint @commerce-klaus/eslint-config-sfcc
```

```bash [Vite+]
vp install -D oxlint @commerce-klaus/eslint-config-sfcc
```

:::

```js [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](/packages/eslint-config-sfcc/#eslint-after-oxlint) instead of running the complete ESLint preset twice.

Enable cartridge-aware TypeScript resolution:

```json{3} [cartridges/jsconfig.json]
{
  "compilerOptions": {
    "plugins": [{ "name": "@commerce-klaus/typescript-sfcc" }]
  }
}
```

Synchronize Salesforce types and check the cartridges:

::: code-group

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

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

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

```bash [Vite+]
vp exec sfcc-ts-sync-types
vp exec sfcc-ts-typecheck
```

:::

To run the same operations through the
[Salesforce B2C CLI](https://salesforcecommercecloud.github.io/b2c-developer-tooling/),
add the Commerce Klaus plugin as a development dependency:

::: code-group

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

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

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

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

:::

Register the project-local plugin after dependency installation:

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

::: code-group

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

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

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

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

::: code-group

```bash [pnpm]
pnpm add -D vitest @commerce-klaus/vitest-sfcc
```

```bash [yarn]
yarn add -D vitest @commerce-klaus/vitest-sfcc
```

```bash [npm]
npm install -D vitest @commerce-klaus/vitest-sfcc
```

```bash [Vite+]
vp install -D vitest @commerce-klaus/vitest-sfcc
```

:::

Configure the same cartridge path used by the application:

```ts [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](/packages/vitest-sfcc/) 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](/packages/vitest-sfcc/) for unit tests that execute cartridge code.
* Use the [Vite plugin](/packages/vite-plugin-sfcc-modules/) when another Vite-based tool needs cartridge-aware module resolution without the test runtime.
* Use the [Babel plugin](/packages/babel-plugin-sfcc-modules/) 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](https://github.com/commerce-klaus/commerce-klaus/tree/main/examples/eslint-typescript-sfcc) 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](https://github.com/commerce-klaus/commerce-klaus/tree/main/examples/oxlint-eslint-sfcc). 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 →](/guide/choosing-a-package)