Blocks reference

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

Boilerplate version: 4.0.1

Quick reference by functionality

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

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 Mini Cart in header (loads early)
2. Defer non-critical blocks below the fold
3. Use Product Recommendations sparingly (loads ML models)

Development workflow

Local testing

1. Start the AEM CLI: aem up
2. Modify block JavaScript in blocks/commerce-*/
3. Changes hot-reload automatically
4. Test with demo backend or configure your own in demo-config.json

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 AEM Custom Blocks documentation for block creation basics.

Related resources

• Boilerplate overview - Complete technical reference
• Configuration guide - 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 demo-config.json
• Styling issues? Review design token configuration in drop-in initializers
• Event not firing? Ensure event bus is initialized and event names match documentation