@commerce-klaus/eslint-config-sfcc

Shareable ESLint flat config for Salesforce Commerce Cloud projects. It catches SFCC script runtime compatibility problems and platform-specific mistakes before code reaches a sandbox.

Highlights

• Detects unsupported syntax and standard library APIs
• Checks SFCC module paths, hooks, and Custom API exports
• Handles Rhino-specific const and scoping behavior
• Includes SFCC and SiteGenesis rules
• Provides Storefront Next, PWA, SFRA, and SiteGenesis policy presets
• Provides additive presets for older SFCC compatibility modes
• Provides a reviewable, safe batch migration away from the SFCC empty() global
• Includes an action-oriented formatter for empty() migration inventories
• Uses Custom Attribute and Site Preference metadata for higher-confidence empty() migration guidance
• Connects parsed Custom API request bodies to generated OAS operation types
• Provides an opt-in preset for enforcing generated project types at metadata boundaries
• Provides an opt-in sfcc-test preset for sequential runtime use, delayed cartridge imports, managed test globals, and safe mock setup
• Supports ESLint and an Oxlint-compatible preset
• Provides equivalent Oxlint override builders for recommended, compatibility, generated-types, empty-migration, storefront architecture, and SFCC test configurations

Prefer Oxlint for everyday linting. It provides the fast feedback loop for normal development and CI and runs the same recommended JavaScript rules over the same server-side cartridge files as ESLint. Use ESLint for complete migrations and audits where .ds files, E4X-like syntax, JavaScript type annotations, JSON metadata, or complex inferred types require its parser and TypeScript services. The full guide documents a focused ESLint fallback for the four rules Oxlint cannot run.

Install

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

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

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

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

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

export default defineConfig(sfcc.configs.recommended)

Projects that generate declarations with @commerce-klaus/typescript-sfcc can add the generated-types preset after recommended:

export default defineConfig(sfcc.configs.recommended, sfcc.configs["generated-types"])

The preset checks registered job step functions, SFCC system hook implementations, Custom API handlers, and local Custom API success response values against their generated types.

The recommended config checks server-side JavaScript below cartridges/ and excludes client-side and static asset folders. It also disables Node.js and browser globals inherited from earlier flat config entries while keeping CommonJS and SFCC runtime globals available.

It also disables selected incompatible rules from ESLint core/recommended, eslint-plugin-unicorn, typescript-eslint, and eslint-plugin-sonarjs. This keeps those presets usable alongside SFCC code without suggesting syntax, APIs, or module patterns unsupported by the SFCC script runtime. See the configuration guide for the documented compatibility overrides.

The recommended config follows the current SFCC Script API. Projects using an older compatibility mode can add the corresponding preset after recommended:

export default defineConfig(sfcc.configs.recommended, sfcc.configs["compatibility-21.2"])

Presets are available for compatibility modes 21.2 and 22.7. The 22.7 preset currently matches the recommended API baseline and establishes an explicit version contract for future Script API additions. The 21.2 preset also prevents Unicorn from suggesting BigInt, globalThis, or Object.fromEntries as replacements.

Documentation

See the complete configuration guide and rule reference.

License

MIT