Learn the Storefront architecture

This overview guides you to the right resources for building headless Adobe Commerce storefronts with Edge Delivery Services , a cloud-based CDN that provides scalable, secure, high-performance hosting for your storefront.

Big picture

Headless Adobe Commerce storefronts on Edge Delivery Services use a composable architecture with domain-driven drop-in components that connect through APIs. These components can be developed, tested, and deployed independently for faster development cycles. This follows an API-first development approach, enabling out-of-process development and extensibility. Drop-in components use Adobe Commerce APIs and integrate out-of-the-box with Edge Delivery Services through the Commerce boilerplate . The storefront supports doc-based authoring, enabling business users to manage content without developer help.

For comprehensive developer documentation on Storefront development, see the Storefront Development guide.

Architecture overview

The following diagram illustrates how Storefront connects to different Commerce backend options:

Loading diagram...

Note

API Mesh for Adobe Developer App Builder can aggregate multiple APIs into a single endpoint for the storefront.

How Storefront works

The following diagram illustrates the flow from authoring to rendering:

Loading diagram...

1. Author creates a cart page with a “Commerce Cart” table in their document.
2. Edge Delivery Services transforms the document server-side into HTML with a <div class="commerce-cart"> element.
3. Browser loads the HTML page and client-side JavaScript decorates the blocks.
4. Block decorator (blocks/commerce-cart/commerce-cart.js) dynamically loads and initializes the Cart drop-in.
5. Drop-in connects to Commerce backend via API and renders the cart UI.

Already have an Adobe Commerce storefront?

You can reuse parts of an existing storefront with an Edge Delivery Services storefront by connecting them with Luma Bridge.

Commerce Boilerplate Architecture

The Commerce Boilerplate follows a modular architecture that separates core AEM functionality from commerce-specific features. It is organized into four main layers:

Loading diagram...

1. scripts.js – Handles core AEM page loading, block decoration, font loading, and orchestration of eager, lazy, and delayed loading. Aligns with the upstream AEM Boilerplate and supports extensibility for global DOM decorators, third-party plugins, and eager code execution.

2. commerce.js – Contains all Commerce Boilerplate-specific logic, including backend connections, template handling, page type detection, Adobe Data Layer initialization, and commerce utilities.

3. Initializers – Scripts that initialize commerce drop-in components (account, cart, order, personalization, and so on), bootstrapping features and integrating them with the storefront.

4. Blocks

   • AEM Blocks: Authored in DA.live, Google Docs, or Microsoft Word using tables. Rendered server-side as HTML <divs> and decorated client-side. Can be enriched with semantic HTML, accessibility attributes, and dynamic DOM transformations.
   • Commerce Blocks: Extend AEM Blocks with Commerce drop-in components, using the same authoring model but dynamically rendering client-side UI based on authored table configuration.

For a detailed breakdown of the file structure and where to find specific files, see the Getting started page.

Drop-in components

Drop-in components are domain-driven commerce components that provide specific functionality for your storefront. They are reusable across projects, connected to Adobe Commerce through APIs, and can be developed, tested, and deployed independently.

Integration patterns are available as pull requests in the Commerce boilerplate repository . Add drop-in components to your project as NPM packages:

B2C Drop-ins:

• @dropins/storefront-account
• @dropins/storefront-auth
• @dropins/storefront-cart
• @dropins/storefront-checkout
• @dropins/storefront-order
• @dropins/storefront-payment-services
• @dropins/storefront-pdp
• @dropins/storefront-recommendations
• @dropins/storefront-wishlist
• @dropins/storefront-personalization
• @dropins/storefront-product-discovery

B2B Drop-ins:

• @dropins/storefront-company-management
• @dropins/storefront-company-switcher
• @dropins/storefront-purchase-order
• @dropins/storefront-quote-management
• @dropins/storefront-requisition-list

Note

Adobe recommends using the documented extension patterns for drop-in components.

Front-end blocks

Blocks are the fundamental parts of a page delivered by Edge Delivery Services, encapsulating styling and code for logical page components. Edge Delivery Services includes predefined “content” and “commerce” blocks that can be customized. Code is managed in GitHub and deployed to Edge Delivery Services.

Content blocks

Components that provide content and layout for non-commerce pages, including Cards, Columns, Headers, Footers, and more. See block collection for more information.

Commerce blocks

Commerce blocks enable Adobe Commerce functionality (cart, checkout, account) and are more tightly integrated with Adobe Commerce APIs than content blocks. For complex state management, the Commerce boilerplate includes examples using a buildless version of Preact and HTM . Use frameworks only for blocks requiring complex state management; otherwise, use plain JavaScript. See existing blocks in the Commerce boilerplate as a reference.

Storefront Compatibility package

The Storefront Compatibility package extends the GraphQL schema provided with Adobe Commerce. It provides new mutations and adds missing fields that are needed to implement low-funnel drop-in components, such as the cart, checkout, user account, and order drop-in components.

Storefront services

Storefront services are multi-tenant services (shared app, many users, separate data) that provide fast access to storefront data via GraphQL APIs. They are not tied to Commerce environment scaling constraints and provide read-only access to catalog data for product pages, search, navigation, and recommendations. Synchronized data is stored in a “SaaS data space” available through Adobe IMS.

These services are required for building a storefront on Edge Delivery Services because only these APIs provide the performance needed for a 100 Lighthouse score. They are available in addition to the core Adobe Commerce GraphQL APIs . For the complete GraphQL schema reference, see the GraphQL API Reference . For an overview of all Commerce web APIs, see Commerce Web APIs .

Adobe Commerce Services Guides

For a complete list of merchandising services, refer to the Adobe Commerce Services Guides .

Data Connection service

The Data Connection extension connects your Adobe Commerce storefront to the Adobe Experience Platform and the Edge Network so that you can enrich and personalize the shopping experience for your customers. Refer to the Data Connection Guide for details and installation instructions.

Services Connector

The Services Connector connects your Commerce storefront to the Commerce backend services listed below. Refer to the Commerce Services Connector Guide for details and installation instructions.

Catalog Service

The Catalog Service module provides fast read-only access to Commerce catalog data. The product details drop-in component requires this service to render product data in the storefront. Refer to the Catalog Service Guide for details and installation instructions.

Live Search

The Live Search service replaces the default Commerce catalog search. This service powers the Product Discovery drop-in component, which provides a variety of customizable controls to showcase your products and build interactive experiences that engage customers.

Live Search uses events to power search algorithms such as “Most Viewed” and “Viewed This, Viewed That”. For headless implementations, learn how to set up eventing for your storefront.

Multiple stores in a single Adobe Commerce environment

When using a single Adobe Commerce environment for multiple stores and only a single store should be migrated to Edge Delivery Services, you may need to contact Adobe Commerce Support to ensure that Live Search is activated without disabling Elasticsearch, which should continue to drive the search of the other stores.

Product Recommendations

Product Recommendations uses AI and machine-learning algorithms ( Adobe Sensei ) to create personalized storefront experiences. While not a strict requirement, it’s recommended for Commerce storefronts. It provides recommendation data for the current shopper context (for example, “Customers who viewed this product also viewed”) and can be placed in several areas of the site. Configure behavior in Adobe Commerce Admin.

Similar to Live Search, Product Recommendations uses events for collecting data. Learn how to implement eventing for your storefront. Refer to the Product Recommendations setup for details.

Adobe Commerce backend options

Storefront supports three distinct customer scenarios. Identify which applies to you:

Quick comparison

Feature	Commerce PaaS	Adobe Commerce as a Cloud Service	Adobe Commerce Optimizer
Storefront bundled	No	Yes	Yes
Setup complexity	Manual installation required	Fully automated	Fully automated
Version management	Self-managed (v2.4.7+)	Automatically managed	Fully managed SaaS
Experience Platform integration	Extension required	Built-in	Built-in
Services configuration	Manual install and configure	Automatically configured	Automatically configured
Best for	Existing PaaS customers	New customers (recommended)	New customers or PaaS + Optimizer

Commerce Platform-as-a-Service (PaaS)

Use case: Existing Adobe Commerce Platform-as-a-Service (PaaS) customers who previously accessed Storefront without Adobe Commerce as a Cloud Service or Adobe Commerce Optimizer licenses.

Adobe Commerce Platform-as-a-Service (PaaS) refers to Adobe Commerce deployments on cloud infrastructure or on-premises.

Prerequisites for PaaS:

• Product license: Adobe Commerce Cloud or on-premises (Magento Open Source is not supported)
• Version: v2.4.7 or later
• PHP: 8.3/8.2 for Adobe Commerce 2.4.7
• Storefront Compatibility package: Must be installed to extend the GraphQL schema. See the Storefront Compatibility package documentation for details.
• Storefront services: Install and configure the latest versions of:
  • Data Connection service
  • Services Connector
  • Catalog Service
  • Live Search
  • Product Recommendations

Note

Installation resources for PaaS:

• System requirements for cloud infrastructure
• Setup for Commerce on cloud infrastructure

Adobe Commerce Optimizer integration: Existing PaaS customers can purchase Adobe Commerce Optimizer and use it with their PaaS deployment. For progressive migration scenarios, see Luma Bridge which supports EDS + Adobe Commerce Optimizer + PaaS configurations.

Adobe Commerce as a Cloud Service

Use case: New Adobe Commerce as a Cloud Service customers with Storefront bundled.

Adobe Commerce as a Cloud Service is the recommended deployment option. It provides a fully managed, scalable, and secure environment. All product requirements and services are automatically managed and updated by Adobe.

Prerequisites for Adobe Commerce as a Cloud Service:

• Product license: Adobe Commerce as a Cloud Service (Storefront is bundled)
• Version: Automatically managed by Adobe
• PHP: Automatically managed by Adobe
• Storefront Compatibility package: Automatically installed and updated by Adobe
• Storefront services: Automatically configured and managed:
  • Experience Platform integration (built-in; no separate Data Connection extension required)
  • Services Connector
  • Catalog Service
  • Live Search
  • Product Recommendations

Note

For Adobe Commerce as a Cloud Service customers, all backend requirements and services are automatically managed by Adobe. No manual installation or configuration is required. Experience Platform integration is built into Adobe Commerce as a Cloud Service, unlike PaaS deployments which require installing the Data Connection extension separately.

Adobe Commerce Optimizer

Use case: New Adobe Commerce Optimizer customers with Storefront bundled, or existing PaaS customers who purchase Adobe Commerce Optimizer and receive Storefront.

Adobe Commerce Optimizer is a SaaS-based commerce solution that includes Storefront bundled.

Prerequisites for Adobe Commerce Optimizer:

• Product license: Adobe Commerce Optimizer (Storefront is bundled)
• Backend services: Fully managed SaaS infrastructure
• Storefront services: Automatically configured and managed:
  • Experience Platform integration (built-in; no separate Data Connection extension required)
  • Services Connector
  • Catalog Service
  • Live Search
  • Product Recommendations

Note

For Adobe Commerce Optimizer customers, all backend requirements and services are automatically managed. Existing PaaS customers can purchase Adobe Commerce Optimizer and use it with their PaaS deployment. For progressive migration scenarios, see Luma Bridge which supports EDS + Adobe Commerce Optimizer + PaaS configurations.