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.

New to cartridge configuration?

If these concepts are new, read Cartridges and cartridge paths before configuring cartridgesDir, cartridgePath, or site metadata.

Install the dedicated configuration package:

pnpm

pnpm add -D @commerce-klaus/config

npm

npm install -D @commerce-klaus/config

Yarn

yarn add -D @commerce-klaus/config

Vite+

vp install -D @commerce-klaus/config

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:

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.

• SN

  Headless

  Storefront Next

  storefront-next

  For cartridges serving Storefront Next without SFRA controllers, forms, storefront ISML rendering, or the legacy Pipeline API.

  Architecture details →
• PWA

  Headless

  PWA

  pwa

  For cartridges supporting a PWA storefront through APIs and headless integration points rather than SFRA controller conventions.

  Architecture details →
• SFRA

  Reference storefront

  SFRA

  sfra

  For Storefront Reference Architecture cartridges using controllers, the server module, forms, and storefront rendering.

  Architecture details →
• SG-C

  Legacy controllers

  SiteGenesis Controllers

  sitegenesis-controllers

  For controller-based SiteGenesis cartridges that do not use the SFRA server module or the legacy Pipeline API.

  Architecture details →
• SG-P

  Legacy pipelines

  SiteGenesis Pipelines

  sitegenesis-pipelines

  For pipeline-era SiteGenesis cartridges. This is the only architecture policy that permits access to the legacy Pipeline API.

  Architecture details →

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 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:

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:

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.