Storefront Architecture
How does an authored document become a live storefront with real product prices, a working cart, and shopper sign-in? This topic explains how the system is built, what each piece does, and where your code fits in.
Storefront
Section titled “Storefront”The storefront is the shopper-facing layer of Adobe Commerce: it renders the UI and connects to Commerce and services through APIs. On Edge Delivery Services, you build that experience with Commerce blocks, drop-in components, and the Adobe Commerce boilerplate.
Edge Delivery Services is a cloud-based content delivery network (CDN) that provides a scalable, secure, and high-performance platform for delivering your storefront to customers. It delivers content at the edge—close to the end user—to reduce latency and improve performance. Adobe Commerce storefronts on Edge Delivery Services support document-based authoring, enabling business users to manage content without developer involvement.
New to Edge Delivery? See the AEM documentation (Build, Publish, Launch) and authoring guide . For Document Authoring on da.live, see Document Authoring documentation .
How the storefront parts fit together
Section titled “How the storefront parts fit together”This section explains how authoring, blocks, drop-in components, and your repository work together so the rest of this topic is easier to follow.
Each table in a document becomes an HTML block—a div with a class name that EDS and your JavaScript use to identify it. Your Git repository holds the code that wires Commerce blocks to drop-in components: block decorators, scripts/initializers/, styles, and storefront configuration. When you push to GitHub, EDS builds and deploys; shoppers receive HTML, CSS, and JavaScript served from the edge.
For more on authoring documents and blocks, see Document Authoring documentation, this guide’s Document Authoring and Universal Editor Quick Starts, and the authoring guide with the full AEM documentation for Edge Delivery Services (build, publish, launch).
Compare content blocks, commerce blocks, and drop-in components
Section titled “Compare content blocks, commerce blocks, and drop-in components”Use this table as a map. Later sections go deeper on each part.
| Content blocks | Commerce blocks | Drop-in components | |
|---|---|---|---|
| Role | Layout and marketing UI (cards, heroes, columns, headers, footers) | Interactive Commerce experiences (cart, checkout, account, PDP, …) | Packaged UI and logic that commerce blocks load and initialize |
| Where it comes from | Block Collection and custom blocks in blocks/ | Commerce blocks in blocks/, mapped in the boilerplate | npm packages such as @dropins/storefront-cart |
| Authored as document tables | Yes | Yes | No—developers add packages and wire initializers in code |
| Typical tie to Adobe Commerce | None—no Commerce GraphQL for most blocks | Yes—GraphQL, REST, and services through the boilerplate | Direct—Commerce API calls (GraphQL, REST, services) are built into each package |
| Learn more | Block Collection | Boilerplate and blocks · Blocks reference | Drop-ins introduction |
Commerce Storefront SDK
Section titled “Commerce Storefront SDK”Drop-in components are built on shared Commerce Storefront SDK patterns—initialization, rendering, slots, and extension hooks—so behavior and structure stay consistent across cart, checkout, product discovery, and the rest of the set.
- Commerce Storefront SDK — Reference for APIs, design components, and utilities used across drop-in components
- Drop-ins introduction — Full map of B2C and B2B drop-in components and how they install into the boilerplate
Terminology for Commerce blocks, drop-in components, and content blocks also appears in the Boilerplate getting started vocabulary.
Headless storefront vs a classic theme
Section titled “Headless storefront vs a classic theme”If you know Luma or another Adobe Commerce theme, that model is different from this one. A classic theme storefront renders many pages with PHP on the Commerce application, such as the theme’s templates and layout controlling cart, checkout, and account. The Commerce storefront on Edge Delivery Services is headless from Commerce’s perspective: Edge Delivery serves the HTML and client-side JavaScript, and drop-in components call Adobe Commerce APIs and shared Commerce Services (catalog, search, recommendations, and more). You are not replacing the Commerce Admin, product catalog, or orders—you are choosing a shopper-facing rendering layer built on documents, blocks, and drop-in components.
If you still run Luma while you adopt Edge Delivery, you can align shopper sessions with Luma Bridge. Backend types and prerequisites (Commerce PaaS, Adobe Commerce as a Cloud Service, Adobe Commerce Optimizer) are covered in Backend options.
How the pieces connect
Section titled “How the pieces connect”The diagram below adds the pieces you implement and operate: Commerce blocks and drop-in components, the Adobe Commerce boilerplate, your backend (Adobe Commerce as a Cloud Service or Adobe Commerce Optimizer), and shared Commerce Services.
When you understand how the pieces fit together, align your storefront with your Commerce backend using Commerce configuration. For backend types and prerequisites, see Backend options.
How a page loads
Section titled “How a page loads”Understanding how content transforms into rendered commerce experiences helps you know where to customize and integrate. The system stack diagram is structural. This diagram adds the time dimension: what happens from document authoring to a Commerce API call when the page loads.
In Edge Delivery Services, a block decorator is the JavaScript module that runs for each block after the page loads. The framework discovers each block’s div in the HTML, loads the matching file under blocks/{block-name}/, and runs its default export function—your decorate(block) code—so the block can build layout and call into drop-in components. The sequence below reads left to right (author → Edge Delivery Services → browser → block decorator → drop-in → Commerce API).
Each stage matches a box in the diagram. In document-based authoring (DA.live, Google Docs, or SharePoint), you create a table in the document (for example, a Commerce Cart table) that EDS turns into a block. In the Universal Editor, you edit blocks visually on the rendered page—no tables are involved. Edge Delivery Services turns it into HTML (for example, <div class="commerce-cart">). The browser loads that HTML. The block decorator (blocks/commerce-cart/commerce-cart.js) runs in the browser. It imports the initializer (which configures the drop-in’s API endpoint and loads UI labels), then calls provider.render() to mount the drop-in component into the block. The drop-in component then fetches from the Commerce API to render the UI.
The sections below go deeper: Boilerplate and blocks (files and block wiring), Drop-in components (the UI packages), and Commerce Services (APIs and GraphQL).
Boilerplate and blocks
Section titled “Boilerplate and blocks”Content blocks and Commerce blocks
Section titled “Content blocks and Commerce blocks”Blocks are the fundamental building parts of a page on Edge Delivery Services. Each block encapsulates the styling and code for one logical section of the page — a hero, a card row, a cart. Both content and commerce blocks are authored as document tables that EDS converts to HTML. The difference is what happens after that conversion:
Content blocks provide layout and marketing UI — cards, columns, headers, footers, and more from the Block Collection . Developers can enrich them with semantic HTML and accessibility attributes. They do not load drop-in components or call Adobe Commerce GraphQL.
Commerce blocks deliver interactive Commerce experiences — cart, checkout, account, PDP, and more. They use the same document-based authoring model as content blocks, but the boilerplate maps them to initializers and @dropins/* packages that call Adobe Commerce GraphQL and related APIs. Prefer plain JavaScript when writing Commerce blocks; React is possible but its bundle size makes a 100 Lighthouse score difficult to achieve. See Libraries in the FAQ and the existing blocks in the Commerce boilerplate as a reference.
Key files and folders
Section titled “Key files and folders”The Adobe Commerce boilerplate is your project’s Git repository. It separates core AEM block delivery from Commerce-specific code — scripts/commerce.js, scripts/initializers/, and storefront configuration — so both sides stay maintainable independently.
The table below maps the key files and folders in the boilerplate scripts/ folder and blocks/.
| File/Folder | Role |
|---|---|
scripts/scripts.js | Page load, block decoration, fonts, and orchestration of eager, lazy, and delayed loading phases. Imports from scripts/aem.js and scripts/commerce.js. Also the extension point for global DOM decorators, third-party plugins (such as experimentation tools), and any code that must run eagerly on page load. |
scripts/commerce.js | Commerce-specific loading, templates, page type detection, Adobe Client Data Layer initialization, and storefront configuration. Centralizes all commerce features and keeps them distinct from core AEM logic. |
scripts/initializers/ | One file per drop-in. Each initializer sets the GraphQL endpoint, loads UI string translations, and registers the drop-in for rendering — all at import time, before any block decorates. See Using drop-ins for the code pattern. |
blocks/ | Commerce and content blocks. See Content blocks and Commerce blocks above and Getting started for the repo layout. |
To go deeper on customizing blocks or connecting the storefront to Commerce: Blocks reference · Blocks configuration · Storefront configuration
Drop-in components
Section titled “Drop-in components”Drop-in components are domain-driven Commerce UI packages that provide specific functionality for your storefront. They are reusable and can be shared across multiple projects. They connect to Adobe Commerce and other services through APIs and can be developed, tested, and deployed independently so teams can iterate on their own timelines.
Drop-in components make Commerce API calls directly from the shopper’s browser. Edge Delivery Services does not proxy or route those requests — it only serves the page HTML, CSS, and JavaScript. This means that if your Commerce backend is behind a VPN or IP allowlist, shoppers’ browsers must be able to reach it directly.
You add drop-ins to your project as npm packages. Drop-in source repositories are private, but the packages are published to npm (for example, npm install @dropins/storefront-cart). Your Commerce blocks and initializers then load and configure those packages on the page.
To see how blocks connect to drop-ins, browse the Commerce boilerplate repository. To customize drop-in behavior beyond what configuration allows, use the documented extension patterns.
The Drop-ins introduction lists B2C and shared packages. B2B storefront flows use additional packages and topics—see Drop-ins B2B for company, quotes, purchase orders, requisition lists, and related experiences.
The list below is B2C-only (@dropins/storefront-*). It illustrates the pattern. B2B package names and installs are covered in Drop-ins B2B. Use the introduction and install topics for each drop-in as the source of truth when package names or versions change.
@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
Commerce Services
Section titled “Commerce Services”Adobe provides a set of hosted Commerce Services—Catalog Service, Live Search, and Product Recommendations—that your storefront calls for fast product data. Adobe hosts these services separately from your Commerce application, syncs your catalog data into them, and exposes that data through their own GraphQL APIs. Because they are purpose-built for storefront reads, they return data faster than querying the Commerce application directly. They do not replace the core Commerce GraphQL API—cart, checkout, and account still use it.
Drop-in components call Commerce Services directly from the browser using the API clients configured in the boilerplate. What you need to install or enable depends on your backend—see Backend options for the full list.
| Service | What it does | Guide |
|---|---|---|
| Data Connection | Connects your storefront to Adobe Experience Platform for enrichment and personalization. | Data Connection Guide |
| Services Connector | Connects your storefront to the Commerce backend services below. | Commerce Services Connector |
| Catalog Service | Fast read-only access to Commerce catalog data that drives product detail pages, product list pages, search, and navigation. Required by the Product Details drop-in. | Catalog Service Guide |
| Live Search | Replaces default Commerce catalog search and powers the Product Discovery drop-in, which provides customizable controls to showcase products and build interactive search experiences. Uses storefront events to drive search algorithms such as “Most Viewed” and “Viewed This, Viewed That”—see Analytics for headless implementation requirements. | Headless data collection |
| Product Recommendations | AI-powered (Adobe Sensei) personalized product recommendations for the current shopper context. Surfaces units such as “Customers who viewed this also viewed” that can be placed in multiple areas of the site; configure unit behavior in the Commerce Admin. Not a strict requirement, but recommended for Commerce storefronts. Requires Analytics for headless implementations. | Headless integration · Drop-in setup |
| Storefront Compatibility package | Extends the GraphQL schema by adding new mutations and missing fields required for cart, checkout, account, and order drop-in components. PaaS (with ACO license): manual install required. Adobe Commerce as a Cloud Service: managed automatically. | Install guide |
How drop-in components communicate
Section titled “How drop-in components communicate”Drop-in components communicate through a shared event bus (@dropins/tools/event-bus.js) using publish-subscribe. Components stay loosely coupled. No drop-in component depends directly on another.
events.on(name, handler, options)— subscribe; returns a subscription handleevents.emit(name, payload)— publish an eventsubscription.off()— unsubscribe (call on the handle returned fromevents.on)
Each drop-in component documents which events it emits and listens to. See the event bus API reference and the drop-in events overview for details.
Migrating from Luma
Section titled “Migrating from Luma”Not migrating from Luma? Skip this section and go to Next steps.
Some projects move content and marketing to EDS first while cart, checkout, or account still run on the Luma theme on Adobe Commerce PaaS. This section covers only that phased, dual-surface setup.
What Luma Bridge does
Section titled “What Luma Bridge does”Use Luma Bridge on Adobe Commerce PaaS when Luma-themed cart, checkout, or account still run on Commerce while content and marketing move to Edge Delivery first.
Drop-in components and the bridge: User authentication and cart run only on EDS. They set cart and authentication cookies. Luma Bridge is a PHP module on Commerce that matches that cookie contract so Luma pages share session with EDS. It does not initialize or plug into drop-in components. Commerce adapts to what drop-in components already do.
- Session behavior — How does session management work?
- Topology and limitations — Luma Bridge (for example, when not to use this approach with PWA Studio or Vue Storefront)
- PaaS + Adobe Commerce Optimizer Connector migrations — Backend options
Migration scenarios
Section titled “Migration scenarios”Next steps
Section titled “Next steps”See also: Get started · Drop-ins introduction · Analytics