@commerce-klaus/typescript-sfcc
TypeScript tooling for Salesforce Commerce Cloud cartridge projects. It provides cartridge-aware editor resolution, command-line type checking, and project-specific generated types while SFCC runtime code remains JavaScript with JSDoc.
Highlights
- Resolves
dw/*,*/,~/, cartridge aliases, andmodule.superModule - Typechecks cartridges with TypeScript 5.5–6 or the TypeScript 7.1+ native API
- Generates types for custom attributes, hooks, Custom APIs, and custom job steps with overridable chunk item types
- Validates hook registrations and statically detectable exports
What Commerce Klaus adds
The official Salesforce B2C Commerce IDE Extension is the preferred foundation for Script API IntelliSense and standard cartridge module resolution in VS Code. The broader Salesforce B2C Developer Tooling also bundles XSD schemas and offers XML validation through its CLI. Commerce Klaus composes with these tools and adds generated project guarantees that can also run outside the editor:
| Area | Commerce Klaus addition | Practical benefit |
|---|---|---|
| Project contracts | Projects metadata, hooks.json, Custom API schemas, and steptypes.json into TypeScript declarations | Configuration and JavaScript implementation are checked together |
| Super modules | Resolves and types module.superModule chains | Cartridge overrides remain navigable and type-safe |
| Type checking | Runs the cartridge-aware TypeScript compiler from the command line | The same class of diagnostics can block CI without a VS Code extension |
| Registration validation | Checks hook descriptors, referenced scripts, and required CommonJS exports | Broken registrations fail before deployment |
| Shared tooling | Reuses the same cartridge semantics across TypeScript, ESLint, Vite, Babel, and Vitest packages | Local tools agree about which cartridge implementation wins |
Install
Salesforce Script API declarations are synchronized through the Salesforce B2C Developer Tooling CLI.
pnpm add -D @commerce-klaus/typescript-sfcc typescript @salesforce/b2c-cli
npm install -D @commerce-klaus/typescript-sfcc typescript @salesforce/b2c-cli
yarn add -D @commerce-klaus/typescript-sfcc typescript @salesforce/b2c-cli
vp install -D @commerce-klaus/typescript-sfcc typescript @salesforce/b2c-cli
While TypeScript 7.1 is on the beta channel, replace typescript with
typescript@beta in the command for your package manager.
With TypeScript 5.5–6, enable the editor plugin in a cartridge jsconfig.json
or tsconfig.json:
{
"compilerOptions": {
"plugins": [{ "name": "@commerce-klaus/typescript-sfcc" }]
}
}
The plugin composes with the
official Salesforce B2C Commerce VS Code extension.
Existing language-service resolutions from Salesforce take precedence; Commerce
Klaus fills unresolved modules and adds generated project declarations and
module.superModule support.
TypeScript 7.1 uses a native language server and no longer loads tsserver plugins. The CLI and type generators support TypeScript 7.1+, but the editor plugin currently requires TypeScript 5.5–6. Projects that only use the CLI and generators can adopt TypeScript 7.1 without installing an older project compiler.
Synchronize types and run the cartridge typecheck:
pnpm exec sfcc-ts-sync-types
pnpm exec sfcc-ts-typecheck
npm exec -- sfcc-ts-sync-types
npm exec -- sfcc-ts-typecheck
yarn exec sfcc-ts-sync-types
yarn exec sfcc-ts-typecheck
vp exec sfcc-ts-sync-types
vp exec sfcc-ts-typecheck
Both standalone commands use the same oclif command implementation as the B2C
CLI plugin, including --help, --json, consistent errors, and color-aware
terminal output. Typechecks use the TypeScript compiler installed by the project,
including when invoked through the B2C CLI plugin.
The Salesforce extension provides editor IntelliSense but does not run a
project-wide TypeScript check. Keep sfcc-ts-typecheck in local and CI workflows
for reproducible diagnostics outside the editor.
The package API also exposes cleanGeneratedTypes() for removing only the four
project-specific sfcc-*.generated.d.ts outputs managed by Commerce Klaus. It
preserves synchronized Salesforce Script API types and unrelated declarations,
and accepts dryRun: true for a read-only preview.
Documentation
See the complete setup, CLI, and generated types reference.
License
MIT