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:

• Most topics include a short "Debugging" section with copy-paste console.log recipes for the non-obvious Spartacus runtime state — resolved OCC endpoints (backend-communication.md), merged config (configuration.md), CMS page structure (cms-component-wiring.md), and translations (i18n.md).