Composable Storefront Engineering: Production Practices for Angular, CMS, and SSR

src/app/features/merchandising/
├── cms/                 # CMS type -> Angular component mapping
├── components/          # Presentational, OnPush components
├── facade/              # Stable UI-facing API
├── data-access/         # OCC adapter / connector / DTO mapping
├── model/               # Project-owned TypeScript types
└── merchandising.module.ts

import { ChangeDetectionStrategy, Component, NgModule } from '@angular/core';
import { CmsConfig, provideDefaultConfig } from '@spartacus/core';

@Component({
  selector: 'cci-merchandising-banner',
  templateUrl: './merchandising-banner.component.html',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class MerchandisingBannerComponent {}

@NgModule({
  declarations: [MerchandisingBannerComponent],
  providers: [
    provideDefaultConfig(<CmsConfig>{
      cmsComponents: {
        CciMerchandisingBannerComponent: {
          component: MerchandisingBannerComponent,
        },
      },
    }),
  ],
})
export class MerchandisingModule {}

import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { CmsComponentData } from '@spartacus/storefront';
import { Observable, map } from 'rxjs';

interface MerchandisingBannerCmsData {
  uid?: string;
  headline?: string;
  copy?: string;
  ctaLabel?: string;
  urlLink?: string;
}

interface BannerViewModel {
  id: string;
  headline: string;
  copy?: string;
  cta?: { label: string; url: string };
}

@Component({
  selector: 'cci-merchandising-banner',
  templateUrl: './merchandising-banner.component.html',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class MerchandisingBannerComponent {
  private readonly component = inject(CmsComponentData<MerchandisingBannerCmsData>);

  readonly vm$: Observable<BannerViewModel> = this.component.data$.pipe(
    map((data) => ({
      id: data.uid ?? 'unidentified-banner',
      headline: data.headline?.trim() || 'Promotion',
      copy: data.copy?.trim() || undefined,
      cta:
        data.ctaLabel?.trim() && data.urlLink?.trim()
          ? { label: data.ctaLabel.trim(), url: data.urlLink.trim() }
          : undefined,
    })),
  );
}

<section *ngIf="vm$ | async as vm" class="cci-banner" [attr.data-cms-id]="vm.id">
  <h2>{{ vm.headline }}</h2>
  <p *ngIf="vm.copy">{{ vm.copy }}</p>
  <a *ngIf="vm.cta as cta" [routerLink]="cta.url">{{ cta.label }}</a>
</section>

import { Injectable } from '@angular/core';
import { combineLatest, Observable, map, shareReplay } from 'rxjs';
import { Product } from '@spartacus/core';
import { ActiveCartFacade } from '@spartacus/cart/base/root';
import { CurrentProductService } from '@spartacus/storefront';

export interface ProductPurchaseState {
  code: string;
  name: string;
  canAddToCart: boolean;
  cartEntryCount: number;
}

@Injectable({ providedIn: 'root' })
export class ProductPurchaseFacade {
  constructor(
    private readonly currentProduct: CurrentProductService,
    private readonly activeCart: ActiveCartFacade,
  ) {}

  get state$(): Observable<ProductPurchaseState | null> {
    return combineLatest([this.currentProduct.getProduct(), this.activeCart.getEntries()]).pipe(
      map(([product, entries]) => this.toState(product, entries.length)),
      shareReplay({ bufferSize: 1, refCount: true }),
    );
  }

  private toState(
    product: Product | undefined,
    cartEntryCount: number,
  ): ProductPurchaseState | null {
    if (!product?.code || !product.name) {
      return null;
    }

    return {
      code: product.code,
      name: product.name,
      canAddToCart: product.purchasable === true,
      cartEntryCount,
    };
  }
}

import { ChangeDetectionStrategy, Component, DestroyRef, inject } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { EventService } from '@spartacus/core';
import { CartAddEntrySuccessEvent } from '@spartacus/cart/base/root';
import { filter } from 'rxjs';

@Component({
  selector: 'cci-cart-announcement',
  template: '<p *ngIf="message">{{ message }}</p>',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class CartAnnouncementComponent {
  private readonly destroyRef = inject(DestroyRef);
  private readonly eventService = inject(EventService);

  message = '';

  constructor() {
    this.eventService
      .get(CartAddEntrySuccessEvent)
      .pipe(
        filter((event) => Boolean(event.productCode)),
        takeUntilDestroyed(this.destroyRef),
      )
      .subscribe((event) => {
        this.message = `${event.productCode} added to cart`;
      });
  }
}

<ng-container *ngIf="purchaseFacade.state$ | async as state">
  <button [disabled]="!state.canAddToCart">Add {{ state.name }}</button>
</ng-container>

// Bad: the inner stream is detached from the outer lifecycle and error path.
this.productCode$.subscribe((code) => {
  this.recommendationService.load(code).subscribe();
});

// Good: route changes cancel an obsolete request; one subscription owns the chain.
readonly recommendations$ = this.productCode$.pipe(
  filter((code): code is string => Boolean(code)),
  distinctUntilChanged(),
  switchMap((code) => this.recommendationService.load(code)),
);

import { Component, ElementRef, Renderer2, inject } from '@angular/core';
import { WindowRef } from '@spartacus/core';

@Component({
  selector: 'cci-sticky-purchase-panel',
  template: '<aside class="purchase-panel"><ng-content /></aside>',
})
export class StickyPurchasePanelComponent {
  private readonly windowRef = inject(WindowRef);
  private readonly renderer = inject(Renderer2);
  private readonly host = inject(ElementRef<HTMLElement>);
  private removeScrollListener?: () => void;

  ngOnInit(): void {
    if (!this.windowRef.isBrowser()) {
      return;
    }

    const nativeWindow = this.windowRef.nativeWindow;
    if (!nativeWindow) {
      return;
    }

    this.removeScrollListener = this.renderer.listen(nativeWindow, 'scroll', () => {
      const isCompact = nativeWindow.scrollY > 320;
      this.renderer.setAttribute(this.host.nativeElement, 'data-compact', String(isCompact));
    });
  }

  ngOnDestroy(): void {
    this.removeScrollListener?.();
  }
}

import { Request } from 'express';
import {
  defaultRenderingStrategyResolver,
  defaultRenderingStrategyResolverOptions,
  NgExpressEngineDecorator,
  ngExpressEngine as engine,
  RenderingStrategy,
  SsrOptimizationOptions,
} from '@spartacus/setup/ssr';

const isCrawler = (request: Request): boolean =>
  /bot|crawl|slurp|spider|mediapartners/i.test(request.get('user-agent') ?? '');

const ssrOptions: SsrOptimizationOptions = {
  // Preserve exclusions such as checkout, my-account, ASM, and SmartEdit behavior.
  renderingStrategyResolver: (request: Request) =>
    isCrawler(request)
      ? RenderingStrategy.ALWAYS_SSR
      : defaultRenderingStrategyResolver(defaultRenderingStrategyResolverOptions)(request),
};

const ngExpressEngine = NgExpressEngineDecorator.get(engine, ssrOptions);

server.engine('html', ngExpressEngine({ bootstrap: AppServerModule }));

import { Injectable, PLATFORM_ID, inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { isPlatformServer } from '@angular/common';
import { makeStateKey, TransferState } from '@angular/platform-browser';
import { Observable, of, tap } from 'rxjs';

interface StoreNotice {
  id: string;
  text: string;
}

@Injectable({ providedIn: 'root' })
export class StoreNoticeService {
  private readonly http = inject(HttpClient);
  private readonly transferState = inject(TransferState);
  private readonly platformId = inject(PLATFORM_ID);

  load(baseSite: string): Observable<StoreNotice[]> {
    const key = makeStateKey<StoreNotice[]>(`store-notices:${baseSite}`);
    const fromServer = this.transferState.get<StoreNotice[] | null>(key, null);

    if (fromServer) {
      this.transferState.remove(key);
      return of(fromServer);
    }

    return this.http.get<StoreNotice[]>(`/occ/v2/${encodeURIComponent(baseSite)}/notices`).pipe(
      tap((notices) => {
        if (isPlatformServer(this.platformId)) {
          this.transferState.set(key, notices);
        }
      }),
    );
  }
}

# Replace values with an authorized non-production deployment.
curl --silent --show-error --fail \
  -H 'User-Agent: Mozilla/5.0' \
  'https://storefront.example.test/en/USD/p/12345' \
  | grep -E '<app-root|data-cms-id'

# In browser DevTools: verify the initial document contains rendered content,
# then verify hydration has not made the same public OCC request twice.