@contentstack/contentstack-spartacus-connector

An open-source Angular feature library that makes Contentstack the CMS engine for an SAP Composable Storefront (Spartacus), while SAP Commerce (OCC) remains the commerce engine.

It overrides Spartacus's CMS adapter layer so page and component content resolve from Contentstack's Content Delivery API instead of /occ/v2/{site}/cms/pages. Product data still hydrates live from SAP at render time.

Status: 0.1.0 — framework core (validated end-to-end against a real Spartacus app + SAP OCC + Contentstack), Live Preview / Visual Editor bindings, and the ng add schematic installer (validated end-to-end against a real Spartacus app). The content model, a reference storefront, and B2B support remain separate deliverables.

What it does

Concern	How
Intercept CMS routing	ContentstackCmsPageAdapter / ContentstackCmsComponentAdapter replace the OCC adapters and query Contentstack by URL slug
Translate the payload	ContentstackCmsPageNormalizer maps the cms_page schema (named per-slot reference fields → resolved component entries) into Spartacus's native CmsStructureModel (page → slots → components), mapping slot field uids to SAP slot names and content-type uids to SAP typecodes
Map content types to components	CmsConfig.cmsComponents maps each SAP typecode (e.g. SimpleResponsiveBannerComponent) to an Angular component
Resolve component-specific fields	ContentstackCmsComponentNormalizer composes three content-type-specific normalizers by typecode (cms/converters/components/): banner media (media_container or a direct file field), navigation (flat nav_node_flat all_nodes pool reassembled into a CmsNavigationNode tree by parent_id), product carousel (OCC product URLs → productCodes)
Hydrate SAP data	Components read the SAP SKU from Contentstack and pull live price/stock/add-to-cart via Spartacus ProductService / ActiveCartFacade (see src/examples/hero-banner)
Bypass SAP SmartEdit	Never imports SmartEditRootModule; smartEditBypassGuard neutralizes inbound preview params
Code-split the integration	ContentstackCmsFeatureModule (the module you import) only registers config; the actual CMS override + Live Preview wiring lives in ContentstackModule, lazy-loaded via CmsConfig.featureModules — the same convention every real Spartacus feature library uses

Supported features & known limitations

Supported

Capability	Notes
Hybrid rendering	OCC serves the base page + all commerce data; Contentstack overrides authored slots. occFallback: true (default) keeps unauthored slots/pages on OCC.
Flat navigation	Header + footer menus of any depth via the *_flat adjacency-list model (all_nodes pool + text parent_id) — resolves in a constant, shallow include chain, so the Delivery API's plan-gated reference-depth cap never applies.
Editorial components	Banner, responsive banner, product carousel, paragraph, tab paragraph, link, flex → stock Spartacus components by SAP typecode; no cmsComponents config needed.
Multi-language	localeMapping (site isocode → Contentstack locale) plus master-locale fallback; includeFallback adds query-time fallback.
Live Preview / Visual Builder	Entry tagging + live updates via CsEditableDirective / CsEmptyBlockParentDirective (non-production).
Access gating	Opt-in per-entry access_tags (_require-login, _require-anonymous, _require-<roleGroupId>).

Known limitations

Limitation	Detail
Page-type resolution	Per-route pages resolve against the single cmsPageContentType (the starter pack authors the home as landing_page). Shared-layout types (product, category) get their own content type via pageTypeMapping (contentTypeUid + sharedSlug) — the pack ships product_page / category_page for this. Serving multiple distinct per-route content types isn't supported yet; unmapped page types fall back to OCC.
Reference fields, not Modular Blocks	Slots are multi-reference fields; the connector resolves referenced component entries via includeReference. Contentstack Modular Blocks (inline composed blocks) are not read — model components as separate content types referenced from the page/shell.
Author into slots the template renders	A component shows only if the SAP page template renders its slot. LandingPage2Template renders Section1, Section2A/2B/2C, Section3–Section5 — there is no bare Section2 (that's CategoryPageTemplate), and Section2A/2B/2C are narrow 1/3-width columns, so full-width content belongs in Section1/Section3–5.
Access gating is presentation-level	Hides content in the client based on the user's SAP login state / role groups — not a server-side security boundary. Off by default (accessControl.enabled: false).
Shared-slug product/category pages	One shared entry serves every PDP / PLP; product and facet data always come from OCC.
Live Preview is non-production	Ignored in production builds; the previewToken grants draft read access — treat it as a secret, keep it out of committed source and prod.
Content i18n only	Content localizes via Contentstack locales; Spartacus's own UI-label i18n is unchanged.

Architecture

Navigation ─▶ Spartacus CmsPageConnector ─▶ CmsPageAdapter (abstract)
                                              └─▶ ContentstackCmsPageAdapter   ← this lib
                                                    ├─ ContentstackClientService ─▶ Contentstack Delivery API
                                                    └─ ContentstackCmsPageNormalizer ─▶ CmsStructureModel
                                                                                          │
Spartacus rendering engine (PageLayout → PageSlot → ComponentWrapper) ◀───────────────────┘
   └─ resolves each slot component via CmsConfig.cmsComponents ─▶ your Angular component
          └─ reads SAP SKU from Contentstack ─▶ ProductService ─▶ live price / stock (SAP OCC)

Install (into a real Spartacus app)

New to this connector? See GETTING_STARTED.md for the full step-by-step walkthrough (content modeling, wiring, and how to verify it worked). The summary below assumes you've already read that or know the shape.

npm install @contentstack/contentstack-spartacus-connector @contentstack/delivery-sdk

1. Import the feature module — after the base Spartacus modules so the adapter overrides win (DI "last provider wins"; the base includes CmsOccModule). In a standard ng add @spartacus/schematics app, add it in SpartacusFeaturesModule or after StorefrontModule:

   import { ContentstackCmsFeatureModule } from '@contentstack/contentstack-spartacus-connector';
   import { ContentstackConfig } from '@contentstack/contentstack-spartacus-connector';
   import { provideConfig } from '@spartacus/core';
   import { Region } from '@contentstack/delivery-sdk';
   
   @NgModule({
     imports: [ContentstackCmsFeatureModule],
     providers: [
       provideConfig(<ContentstackConfig>{
         contentstack: {
           delivery: {
             apiKey: environment.cs.apiKey,
             deliveryToken: environment.cs.deliveryToken,
             environment: 'production',
             region: Region.EU,
           },
           cmsPageContentType: 'cms_page',
           slugField: 'url',
           // includeReferences defaults to all cms_page slot + header/footer
           // fields (so components resolve inline) — override only to narrow it.
         },
       }),
     ],
   })
   export class ContentstackFeatureModule {}

2. Map your content/component types to components — follow the pattern in src/examples/hero-banner/custom-hero.module.ts. The cmsComponents map key must equal the SAP typecode the normalizer emits (e.g. SimpleResponsiveBannerComponent), mapped from the Contentstack content-type uid via src/cms/model/slot-maps.ts (custom types fall back to their raw uid).

3. (Optional) SmartEdit bypass guard — attach smartEditBypassGuard to your content route to strip legacy SmartEdit preview params.

Connect to your stack

Four values point the storefront at your Contentstack stack:

Value	Where to get it
apiKey	Settings → Stack settings → API Key
deliveryToken	Settings → Tokens → Delivery Tokens (scope it to your environment)
environment	your publishing environment, e.g. development
region	your stack's data center (Region.US / EU / AZURE_NA / …)

Put them in src/environments/contentstack.environment.ts — copy contentstack.environment.example.ts as a starting point (or let ng add generate it). Then set cmsPageContentType (the starter pack authors the home as landing_page) and, for a localized site, localeMapping.

Secret hygiene: apiKey + deliveryToken are read-only and safe in the client bundle. A previewToken (Live Preview only) is a secret — keep it out of committed source; .env* is already gitignored, and you can gitignore the real credentials file or swap it per build via Angular fileReplacements.

Configuration reference

Every option lives on the ContentstackConfig interface (src/config/contentstack-config.ts) and is fully typed — because the library augments Spartacus's Config, your editor autocompletes and type-checks the whole provideConfig(<ContentstackConfig>{ contentstack: … }) block, with each field's JSDoc on hover. The complete set:

contentstack.delivery — connection & credentials

Option	Required	Default
apiKey	yes	—
deliveryToken	yes	—
environment	yes	—
region		Region.US
branch		main
livePreview		false
previewToken	when livePreview	—
previewHost		US preview host

contentstack — behavior

Option	Default / note
cmsPageContentType	page content type queried by slug (the starter pack uses landing_page)
slugField	url — field holding the page slug
slugTransform	{ pattern, replacement } regex rewrite of the route slug before querying
localeMapping	site isocode → Contentstack locale (e.g. { en: 'en-us' }); identity fallback
includeFallback	false — request master-locale fallback for unlocalized entries
occFallback	true — hybrid (OCC base + CS overrides); false = full-replacement
globalSlots	{ contentType, title? } — shared shell merged into every page
pageTypeMapping	per-PageType { contentTypeUid, slugField?, sharedSlug? } (shared-layout pages)
additionalSlotFields	extra { fieldUid: 'SapSlotPosition' } beyond the built-in slot map
componentContentType	content type for standalone component lookups (else components ship in pages)
componentTypeMapping	block uid → SAP typeCode (for author-named blocks without a type_code)
includeReferences	reference fields to expand; defaults to all slot + header/footer fields
accessControl	presentation-level gating — see below
timeoutMs	10000 — Delivery API call timeout

contentstack.accessControl — opt-in content gating (see also CONTENT-MODEL.md §4.5)

Option	Default
enabled	false
accessField	access_tags
anonymousToken	_require-anonymous
loginToken	_require-login
rolePrefix	_require- (role b2badmingroup → _require-b2badmingroup)
gateSharedSlugPages	false

Set delivery.livePreview: true (with a previewToken) to enable Live Preview / Visual Builder; import the library's CsEditableDirective / CsEmptyBlockParentDirective in your slot/component templates for per-field and empty-slot editing.

Verification

This library targets @spartacus/* public contracts; full end-to-end run requires a live SAP OCC backend + Contentstack stack. In-repo verification:

• Typecheck against contracts (offline gate):

  npm run typecheck

  Resolves @angular/*/rxjs/@ngrx/store from this repo's own node_modules (install as devDependencies — they're genuinely on the public registry) and @spartacus/* / @spartacus/schematics from typings/ (transcribed from the real Spartacus source). Exit 0 = our adapters, normalizers, LP/VE services, and schematic conform to the real contract shapes. (Previously pointed at a sibling ../spartacus/ monorepo — not required anymore.)
• Unit tests:
  • npm test — contentstack-cms-page.normalizer.spec.ts / contentstack-cms-component.normalizer.spec.ts plus the three component-specific normalizer specs (cms/converters/components/*.normalizer.spec.ts) and cms/model/type-guards.spec.ts, all pure-logic Contentstack→Spartacus transforms via lightweight stubs (test/stubs/). contentstack-cms.module.spec.ts and examples/hero-banner/custom-hero.component.spec.ts need the full Angular + Spartacus runtime and are intentionally not matched here — verify those inside an integrated Spartacus host app.
  • npm run test:schematics — the ng add schematic via the real SchematicTestRunner, against a test-only @spartacus/schematics stub (test/stubs/spartacus-schematics.stub.ts) compiled into a real local package (the schematics engine require()s it directly at Node runtime; see the stub's doc comment). Verifies collection.json/schema.json wiring, not Spartacus's real installer behavior end to end.
  • npm run test:all — both of the above.

Notes

• typings/ shims exist only for the offline typecheck; they are unused once the real @spartacus/* / @contentstack/delivery-sdk packages are installed.
• See GETTING_STARTED.md for a full installation walkthrough and TROUBLESHOOTING.md for common integration issues.

License

MIT