---
url: /commerce-klaus/guide/project-configuration.md
---
# Project configuration

Commerce Klaus packages can share project-wide SFCC settings from a
`commerce-klaus.config.ts` or `commerce-klaus.config.js` file. Put the file at
the workspace root; tools search from their working directory toward the
filesystem root.

::: info New to cartridge configuration?

If these concepts are new, read [Cartridges and cartridge paths](/guide/cartridges-and-cartridge-paths) before configuring `cartridgesDir`, `cartridgePath`, or site metadata.

:::

Install the dedicated configuration package:

::: code-group

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

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

```bash [Yarn]
yarn add -D @commerce-klaus/config
```

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

:::

```ts [commerce-klaus.config.ts]
import { defineConfig } from "@commerce-klaus/config"

export default defineConfig({
  cartridgesDir: "cartridges",
  architectures: {
    "storefront-next": ["app_headless", "bc_custom_api"],
    sfra: ["app_storefront_base", "modules"],
    "sitegenesis-controllers": ["bm_tools"],
  },
  siteTemplatePath: "sites/site_template",
  site: "RefArch",
})
```

JavaScript configuration uses the same shape:

```js [commerce-klaus.config.js]
export default {
  cartridgesDir: "cartridges",
  cartridgePath: ["app_custom", "app_storefront_base", "modules"],
}
```

Paths in the central file are resolved relative to that file. This makes the
configuration stable when a tool runs from a package or cartridge directory.

## Options

| Option               | Type                                               | Description                                                                       |
| -------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------- |
| `cartridgesDir`      | `string`                                           | Directory containing the project cartridges.                                      |
| `cartridgePath`      | `string[]`                                         | Explicit cartridge order. The first matching cartridge wins.                      |
| `architectures`      | `Partial<Record<CartridgeArchitecture, string[]>>` | Architecture policy assignments by cartridge name.                                |
| `siteTemplatePath`   | `string`                                           | Site-template root containing `sites/<site>/site.xml`.                            |
| `site`               | `string`                                           | Site identifier used to read `custom-cartridges` from `site.xml`.                 |
| `solutionConfigPath` | `string`                                           | Solution `jsconfig.json` or `tsconfig.json` used to infer cartridge order.        |
| `envCartridgePath`   | `string`                                           | Colon- or comma-separated cartridge order, matching Salesforce `SFCC_CARTRIDGES`. |

## Cartridge architectures

A cartridge architecture is an explicit **project policy label**. It tells Commerce Klaus which
storefront conventions a cartridge intentionally follows; it is not inferred from the cartridge
name or directory structure.

::: info Classification does not change cartridge precedence

Architecture assignments do not reorder the cartridge path, create dependencies between
cartridges, or change what SFCC deploys. They let individual tools apply architecture-specific
lint policies or select a focused subset while preserving the existing cartridge-path order.

:::

Read [Cartridge architectures](/guide/cartridge-architectures) for detailed
profiles, the ESLint policy matrix, focused test selection, and guidance for
mixed storefront generations.

The optional `architectures` map is most useful in repositories that contain
more than one storefront generation. Assign each cartridge to at most one
architecture:

```ts [commerce-klaus.config.ts]
export default defineConfig({
  architectures: {
    "storefront-next": ["app_headless", "bc_custom_api"],
    sfra: ["app_storefront_base"],
    "sitegenesis-controllers": ["bm_tools"],
  },
})
```

Commerce Klaus rejects unknown architecture names and cartridges assigned to
more than one architecture. Shared or infrastructure cartridges can remain
unassigned when no architecture policy applies to them.

| Consumer      | How it uses the assignment                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------ |
| ESLint        | `createCartridgeArchitectureConfig()` creates cartridge-scoped policy overlays.                              |
| Oxlint        | `createOxlintArchitectureOverrides()` exposes the same policies as generated overrides.                      |
| `vitest-sfcc` | `cartridgeSelection` selects assigned cartridges for one test project without changing their relative order. |

When Vitest selects an architecture, unassigned cartridges are excluded by
default. Add shared cartridges explicitly or set `includeUnassigned: true` when
the test module graph requires them.

## Overrides

Existing package options and CLI flags remain supported. They override matching
values from the central file, so a test configuration can replace only its
cartridge path:

```ts [vitest.config.ts]
import sfccVitest from "@commerce-klaus/vitest-sfcc"
import { defineConfig } from "vitest/config"

export default defineConfig({
  plugins: [
    sfccVitest({
      cartridgePath: ["app_test", "app_custom", "app_storefront_base"],
    }),
  ],
})
```

Vite, Vitest, Babel, ESLint, and the TypeScript tooling discover the file
automatically. Resolver-based adapters also accept `configFile` with an explicit
path, or `false` to disable discovery for an isolated invocation.

The effective precedence is:

1. package option or CLI flag
2. `commerce-klaus.config.ts` or `commerce-klaus.config.js`
3. the package's existing environment and inference fallbacks

None of the existing configuration mechanisms are deprecated.

## Programmatic API

`@commerce-klaus/config` exports `defineConfig()`, `findCommerceKlausConfig()`,
`loadCommerceKlausConfig()`, `resolveCommerceKlausConfig()`,
`normalizeCartridgeArchitectureAssignments()`,
`filterCartridgePathByArchitecture()`, `CARTRIDGE_ARCHITECTURES`, and the
corresponding architecture types for custom tooling. This keeps project
configuration independent from the internal module resolution implementation.