Blocks reference

This reference provides technical details for all Commerce blocks included in the boilerplate. Each block integrates one or more drop-in components to provide complete Commerce functionality.

Quick reference by functionality

The Merchant topic column links to merchant-facing documentation when you need the block title authors use in documents. The Block column links to the GitHub source folder.

Block	Merchant topic	Primary Drop-ins	Key Features
Shopping Experience
Product List Page	Product List Page	storefront-product-discovery, tools, storefront-wishlist, storefront-requisition-list, storefront-cart	Search, filtering, sorting, pagination, wishlist integration
Product Details	Product Details	tools, storefront-pdp, storefront-wishlist, storefront-requisition-list	Product options, pricing, add to cart, wishlist toggle
Product Recommendations	Product Recommendations	tools, storefront-cart, storefront-recommendations, storefront-wishlist	AI-powered recommendations, multiple page types
Cart	Commerce Cart	tools, storefront-cart, storefront-wishlist, storefront-quote-management	Item management, coupon codes, gift options, move to wishlist
Mini Cart	Commerce Mini Cart	storefront-cart, tools	Dropdown cart summary, quick view, checkout navigation
Checkout	Commerce Checkout	tools, storefront-order, storefront-checkout	Complete checkout flow, shipping, payment, order review
Customer Account
Login	Commerce Login	storefront-auth	Email/password authentication, redirect handling
Create Account	Commerce Create Account	storefront-auth	Registration form, validation, account creation
Confirm Account	Commerce Confirm Account	storefront-auth, tools	Email confirmation landing, account activation
Forgot Password	Commerce Forgot Password	storefront-auth, tools	Password reset request, email trigger
Create Password	Commerce Create Password	storefront-auth, tools	Password reset form, token validation
Account Header	Commerce Account Header	tools	Customer name display, logout functionality
Account Sidebar	Commerce Account Sidebar	tools, storefront-account	Account navigation menu, active state management
Addresses	Commerce Addresses	storefront-account	Address CRUD operations, default address management
Customer Information	Commerce Customer Information	storefront-account	Profile editing, email/name updates
Customer Details	Commerce Customer Details	storefront-order	Customer info display in order context
Order Management
Orders List	Commerce Orders List	storefront-account, tools	Order history, status display, order details navigation
Search Order	Commerce Search Order	storefront-auth, storefront-order, tools	Guest order lookup, email and order number validation
Order Header	Commerce Order Header	tools	Order number, date, status badge
Order Status	Commerce Order Status	storefront-order	Detailed status, tracking info, delivery estimates
Order Product List	Commerce Order Product List	storefront-order, storefront-cart, tools	Line items, reorder functionality, product images
Order Cost Summary	Commerce Order Cost Summary	storefront-order	Subtotal, taxes, shipping, discounts, grand total
Shipping Status	Commerce Shipping Status	storefront-order, tools	Shipment tracking, carrier info, delivery status
Returns & Exchanges
Returns List	Commerce Returns List	storefront-order, tools	Return history, status tracking, return details navigation
Create Return	Commerce Create Return	storefront-order, tools	Return request form, item selection, reason codes
Order Returns	Commerce Order Returns	tools, storefront-order	Return details for specific order
Return Header	Commerce Return Header	tools	Return number, date, status display
Gift Options
Gift Options	Commerce Gift Options	storefront-cart	Gift messages, gift wrapping, gift receipt options
Wishlist
Wishlist	Commerce Wishlist	storefront-cart, storefront-pdp, storefront-wishlist, storefront-auth, tools	Saved items, move to cart, item management

Integration patterns

Block decoration flow

Every Commerce block follows this initialization pattern:

1. Server-side rendering: Edge Delivery Services transforms the document table into HTML
2. Client-side decoration: The block’s JavaScript decorator runs via decorateBlock()
3. Drop-in initialization: Drop-in containers are initialized with configuration and providers
4. Rendering: Drop-in components render into the block’s DOM
5. Event handling: Event listeners connect to the global event bus

Common integration patterns

Simple drop-in rendering

Blocks like Login and Forgot Password simply render a single drop-in container:

export default async function decorate(block) {
  const { render } = await import('@dropins/storefront-auth/containers/SignIn.js');
  await render(SignInContainer, {})({});
}

Multi-drop-in coordination

Complex blocks like Cart and Checkout coordinate multiple drop-ins:

// Cart block uses cart + wishlist drop-ins
import { render as renderCart } from '@dropins/storefront-cart/containers/Cart.js';
import { render as renderWishlist } from '@dropins/storefront-wishlist/api.js';

Configuration from block tables

Blocks read configuration from document authoring tables:

const config = readBlockConfig(block);
const hideHeading = config['hide-heading'] === 'true';

Event bus integration

Blocks listen to events from drop-ins and other blocks:

events.on('cart/updated', () => {
  // React to cart changes
});

Implementation details

Drop-in dependencies

All drop-ins are loaded via import maps defined in head.html:

{
  "imports": {
    "@dropins/storefront-cart/": "/scripts/__dropins__/storefront-cart/",
    "@dropins/storefront-checkout/": "/scripts/__dropins__/storefront-checkout/"
  }
}

Provider initialization

Drop-ins require providers to be initialized in scripts/initializers/:

• GraphQL provider: Configures Commerce backend endpoint and headers
• Authentication provider: Manages customer sessions and tokens
• Event provider: Sets up the global event bus

See Configuration for provider setup details.

Styling

Each block includes:

1. Base styles: Block-specific CSS in blocks/*/block-name.css
2. Drop-in tokens: Design tokens in scripts/initializers/dropin-name.js
3. Global tokens: Shared tokens in scripts/initializers/

Blocks by page type

Essential implementations

Every storefront requires these pages:

• Homepage: Product Recommendations, Product List Page
• Product Page (PDP): Product Details, Product Recommendations
• Cart Page: Cart, Product Recommendations
• Checkout Page: Checkout
• Account Dashboard: Account Header, Account Sidebar

Common additions

Enhance your storefront with:

• Wishlist Page: Wishlist
• Order Tracking: Search Order, Order Status, Orders List
• Returns Portal: Create Return, Returns List, Order Returns
• Account Management: Addresses, Customer Information

Performance considerations

For storefront-wide guidance see Performance best practices.

Lazy loading

Commerce blocks are lazy-loaded automatically:

1. Blocks below the fold are loaded when scrolled into view
2. Drop-in containers are code-split and loaded on demand
3. Heavy dependencies (like checkout) are loaded only when needed

Critical rendering path

For optimal performance:

1. Keep the Mini Cart badge and search button in the header — visible on every page — but load their full panels only when the shopper opens them.
2. Defer non-critical blocks below the fold.
3. Use Product Recommendations sparingly (loads ML models).

Any block or drop-in container that’s hidden by default should follow the same pattern. See Load hidden UI on demand in Performance best practices.

Development workflow

Local testing

1. Start the AEM CLI: aem up.
2. Modify block JavaScript in blocks/commerce-*/.
3. Observe changes hot-reload automatically.
4. Test with demo backend or configure your own in config.json (copy from demo config or use the config generator tool ).

Adding new blocks

To create a custom Commerce block:

1. Create a new directory: blocks/my-custom-block/
2. Add decorator: my-custom-block.js
3. Add styles: my-custom-block.css
4. Import and render drop-in containers
5. Initialize required providers

See Exploring blocks (AEM documentation) for block creation basics.

Related resources

• Boilerplate overview - Complete technical reference
• Configuration page - Setup and provider configuration
• Drop-in documentation - Drop-in technical details
• Merchant block reference - Business user perspective
• Boilerplate blocks source code

Need help?

• Block not rendering? Verify drop-in providers are initialized in scripts/initializers/
• GraphQL errors? Check Commerce backend configuration in your config.json file
• Styling issues? Review design token configuration in drop-in initializers
• Event not firing? Ensure event bus is initialized and event names match documentation