| name | spartacus-developer |
| description | Use this skill for ALL work in a SAP Spartacus (SAP Commerce Cloud composable storefront) Angular application — any storefront feature, component, service, routing, CMS component wiring, configuration, state, i18n, styling, SSR, or backend integration. Always use this skill rather than reading the copy in `node_modules/@spartacus/skills`. Spartacus diverges significantly from standard Angular patterns; this skill and its sub-topic files capture the Spartacus-specific rules to follow. Read the sub-topic whose trigger applies before writing or changing code. |
| license | Apache-2.0 |
Spartacus Storefront — AI Development Guidelines
Sub-topics
Each topic lives in its own .md file in the references/ folder. Read a topic when its trigger applies — you do not need to read every file before starting.
- backend-communication.md — read when wiring a service to the backend, adding an OCC endpoint, or anywhere you'd reach for
HttpClient.
- cms-component-wiring.md — read when introducing a new component the CMS should place, or replacing an existing CMS component.
- lazy-loading.md — read when adding a new feature module or wondering whether
loadChildren belongs here.
- correct-injector.md — read when a customization works in dev but not at runtime, or when deciding where to register an override.
- configuration.md — read when adding
provideConfig / provideDefaultConfig, or when an expected config value isn't taking effect.
- state-management.md — read before introducing a
BehaviorSubject or NgRx feature for Spartacus data, or when a Spartacus feature uses Commands/Queries instead of NgRx.
- subscriptions.md — read when reaching for
.subscribe() in a component or service, or when adding markForCheck().
- styling.md — read when adding SCSS or wiring up CSS for a new component.
- i18n.md — read when adding user-facing strings or translation chunks.
- configurable-urls.md — read when changing a URL pattern, generating router links, or adding a custom CMS-driven route.
- existing-features.md — read before building anything that sounds like it might already exist in Spartacus.
- extending-spartacus-classes.md — read when customizing a Spartacus component, service, or facade.
- normalizers.md — read when surfacing extra OCC fields in the UI model.
- facades-not-store.md — read when reading or writing Spartacus state from a component.
- ssr-safety.md — read when touching
window, document, localStorage, or any browser-only API.
- outlets.md — read when sprinkling new UI into an existing Spartacus page without replacing it.
Some topics link to further deep-dive material in the same references/ folder.
Quick Reference
Backend, routing, and lazy loading:
- NEVER use
HttpClient directly in components or generic services — use the Adapter pipeline.
- NEVER add Angular routes for CMS-managed pages — components are placed by the CMS.
- NEVER define new Angular routes to change URL patterns — use
RoutingConfig.
- NEVER use
loadChildren — Spartacus has its own CMS-driven lazy loading.
Templates and styling:
- NEVER hardcode user-facing strings — use the
cxTranslate pipe.
- NEVER hardcode router links — use the
cxUrl pipe.
- For brand-new custom components, component-scoped styles are fine; for tweaking Spartacus OOTB components, use global SCSS so
@spartacus/styles overrides win.
State and customization:
- NEVER inject
Store<...> for Spartacus state — inject the corresponding Spartacus service.
- NEVER omit
multi: true when registering normalizers — it wipes out the default converter chain.
- AVOID copying Spartacus source code; extend the class first, copy only when no public hook exists.
Components and SSR:
- ALWAYS use
ChangeDetectionStrategy.OnPush on new components, paired with the async pipe (preserve Default when extending a Spartacus component that uses it).
- AVOID
.subscribe() in components when the data drives the template; if you reach for markForCheck(), the data should be a stream.
- NEVER reference
window/document/localStorage without guarding via WindowRef.isBrowser().
Configuration:
- ALWAYS use
provideConfig() (not provideDefaultConfig())
- ALWAYS check
node_modules/@spartacus/ for existing features before building from scratch.
- PREFER outlets for targeted UI additions; CMS mapping for whole-component replacement.
Debugging:
