Storefront Architecture

Headless Adobe Commerce storefronts on Edge Delivery Services use drop-in components that connect through APIs and integrate with the Commerce boilerplate .

Content is authored in documents (DA.live, Google Docs, SharePoint), in-context (Universal Editor, Storefront Builder), or AEM Sites—and rendered as blocks. See the AEM authoring guide for details.

This page explains the architecture, then points you to Backend options to identify your backend and confirm prerequisites.

Architecture overview

Loading diagram...

Storefront architecture: blocks and drop-ins connect to the Commerce boilerplate, which routes to your backend (PaaS, Adobe Commerce as a Cloud Service, or Adobe Commerce Optimizer) and Commerce services.

How it works

Loading diagram...

Flow from authoring to rendering: document table → HTML → block decoration → drop-in initialization → GraphQL fetch.

An author creates a table (for example, Commerce Cart) in a document or uses in-context editing. Edge Delivery Services transforms it to HTML (<div class="commerce-cart">). The browser loads the HTML, the block decorator initializes the drop-in, and the drop-in fetches from the Commerce API to render UI.

What you'll touch

Your storefront project has three moving parts: the boilerplate (config + blocks), drop-in components (commerce UI), and Commerce services (APIs). The sections below explain each one.

Boilerplate and blocks

The Commerce Boilerplate has four layers:

• scripts.js — Page load, block decoration, fonts
• commerce.js — Backend connections, templates, data layer
• initializers — Cart, checkout, account, and more
• blocks — Content blocks (Cards, Columns, Headers) and Commerce blocks (cart, checkout, account)

Commerce blocks use Commerce APIs; the boilerplate uses Preact /HTM for complex state. See Getting started for file structure.

Customize

Blocks reference · Blocks configuration · Storefront configuration

Drop-in components

Drop-ins are domain-driven commerce components. Install from NPM (for example, npm install @dropins/storefront-cart). Use the extension patterns when customizing.

Existing storefront?

Reuse parts of an existing Luma storefront with an Edge Delivery Services storefront by connecting them with Luma Bridge. Luma Bridge works without an Adobe Commerce Optimizer license or the Adobe Commerce Optimizer Connector. It is the session bridge between EDS and Luma/PHP pages.

Loading diagram...

Luma Bridge scenarios: PaaS + Luma can use Luma Bridge without Adobe Commerce Optimizer. PaaS + Adobe Commerce Optimizer can also use Luma Bridge while migrating. Adobe Commerce as a Cloud Service + Adobe Commerce Optimizer has no Luma storefront, so Luma Bridge does not apply.

Event system

Drop-ins communicate through a shared event bus (@dropins/tools/event-bus.js) using a publish-subscribe pattern. This keeps components loosely coupled. No drop-in depends directly on another.

Loading diagram...

Solid arrows: events emitted. Dashed arrows: events consumed. Your custom code (pink) can emit and listen to events alongside drop-ins.

• events.on(name, handler) — subscribe to an event
• events.emit(name, payload) — publish an event
• subscription.off() — unsubscribe

Each drop-in indicates which events it emits and listens to. See the event bus API reference and the drop-in events overview for details.

Events vs. analytics

The event bus handles internal communication between drop-ins on the page. It is separate from ACDL analytics events, which send user behavior data to Adobe Commerce services (Live Search, Product Recommendations).

Backend options and next steps

Storefront supports three backend types: Commerce PaaS, Adobe Commerce as a Cloud Service, and Adobe Commerce Optimizer. Prerequisites and setup differ by backend.

1. Backend options — Comparison table, prerequisites by backend
2. Storefront Setup — Create your storefront and configure your backend