Boilerplate overview

Building a Commerce storefront from scratch means wiring up hosting, drop-in components, and Commerce APIs yourself. The Commerce boilerplate gives you that foundation already built, so you clone one repository and start customizing right away.

What is the Commerce boilerplate?

The Commerce boilerplate is Adobe’s supported starter/reference codebase for storefronts on Edge Delivery ServicesAdobe's hosting and delivery infrastructure that turns authored documents into fast HTML pages served from servers close to the shopper. You push code to GitHub; Edge Delivery Services builds and publishes automatically. (EDS). You clone it from GitHub, connect your Commerce backend, and customize blocks, scripts, and styles in that repository instead of tying together every Commerce integration yourself.

The boilerplate repository lives at hlxsites/aem-boilerplate-commerce . EDS hosts and publishes your site from that repo. The boilerplate also bundles Drop-in componentsNPM packages that provide core Commerce storefront features such as cart, checkout, product details, and account flows. for cart, checkout, product listings, and related Commerce flows so you theme and configure shipped UI rather than building those screens from scratch.

One supported boilerplate

aem-boilerplate-commerce is the only Adobe-supported Commerce starter/reference storefront. Demo storefronts (for example Citisignal) are forks for events or showcases. They often lag behind this repository and are not a safe starting point for your own project.

Exploring the code

The tree below shows the main folders plus important files at the repository root. The table links each folder to GitHub so you can open the matching source tree.

aem-boilerplate-commerce/
├── blocks/                 # Commerce blocks and content blocks
├── scripts/
│   ├── aem.js               # core AEM/Edge Delivery runtime — do not edit
│   ├── scripts.js           # page load orchestration (eager, lazy, delayed)
│   ├── commerce.js          # Commerce loading, templates, storefront configuration
│   ├── delayed.js           # third-party scripts and analytics, loaded after initial render
│   ├── initializers/        # one initializer file per drop-in (endpoints, labels, and related settings)
│   └── __dropins__/         # generated drop-in assets from npm install — do not edit
├── styles/                 # global CSS, lazy-loaded CSS, and font-face declarations
├── fonts/                  # self-hosted font files
├── icons/                  # SVG icons used by blocks
├── tools/                  # the PDP metadata tool
├── cypress/                # end-to-end tests
├── build.mjs               # customizes the Commerce data drop-ins fetch (see Customizing blocks)
├── demo-config.json        # sample storefront configuration; copy to config.json for your project
└── package.json            # dependencies, scripts, and drop-in install hooks

Directory	Purpose
blocks/	Contains Commerce blocks and content blocks, such as header, footer, and cards.
scripts/	Contains the AEM/Edge Delivery runtime, drop-in initializers, and Commerce utilities. See Files to keep unchanged before you edit anything here.
styles/	Contains global styles, lazy-loaded styles, and font-face declarations.
fonts/	Contains the self-hosted font files the storefront ships by default.
icons/	Contains the SVG icons blocks use, such as cart and chevron icons.
models/	Contains per-block authoring model definitions.
tools/	Contains the product detail page (PDP) metadata tool.
cypress/	Contains the boilerplate’s end-to-end test suite.

demo-config.json is a sample, not a live configuration. See Link your repository to Commerce data to generate your own config.json. For build.mjs and the rest of the customization layers, see Where to customize in Customizing blocks.

To understand how documents become rendered commerce experiences at runtime, see How a page loads in Architecture. For a worked example of how blocks/ and scripts/initializers/ wire a block to a drop-in, see Blocks and drop-ins.

Running locally

If you still need to create the GitHub repository, connect Commerce, and initialize Document Author content, follow Create a storefront first.

Run the storefront locally so you can preview changes before you push them. If you already ran git clone while following Create a storefront, start with the npm install step below.

1. Install the project dependencies.

   npm install

2. Start the local development server.

   npm start

3. Open http://localhost:3000 in your browser.

Your storefront appears in the browser at http://localhost:3000.

Tip

If npm install fails, confirm that Node.js and npm are installed on your machine. If npm start fails, check whether another local server is already using port 3000.

Optional: Install the aem command globally with npm install -g @adobe/aem-cli to run the CLI from any directory.

Key runtime packages

After npm install, package.json resolves many dependencies. Use this table when you trace dependencies or debug install issues.

Package	Purpose
@dropins/tools	Shared utilities for all drop-ins (GraphQL client, event bus, initializers, UI components)
@adobe/adobe-client-data-layer	Standardized data layer for event collection and analytics
@adobe/magento-storefront-event-collector	Collects Commerce-specific user interaction events
@adobe/magento-storefront-events-sdk	SDK for sending events to Adobe Commerce for Live Search and Product Recommendations

Customizing your storefront

Styles, blocks, drop-ins, Commerce wiring, and third-party scripts each live in their own layer of the boilerplate. See Customize blocks for which files and layers to change, which to leave alone, and when to isolate your changes in new files.

Deploying your storefront

Edge Delivery Services creates preview and production URLs when you push changes:

• Preview: https://<branch>--<repo>--<owner>.aem.page
• Production: https://<branch>--<repo>--<owner>.aem.live

You do not run a separate deployment build command for Edge Delivery. The Edge Delivery pipeline handles page delivery and optimization after you push.

Push your production changes to the main branch. Caching and push invalidation only work as intended there, so other branches’ .live URLs can serve stale content.

Keeping your storefront current

Track boilerplate changes in the Boilerplate changelog and Release notes. For guidance on upgrading drop-in components, applying updates, and handling breaking changes, see the Updates page.

Related resources

Resource	Description
Drop-in components	API reference for each drop-in component.
Commerce blocks page	Business user page for using blocks.
Universal Editor (deprecated)	Legacy UE instrumentation reference for existing Document Authoring projects.