The Boilerplate

Getting started

This guide provides practical steps for creating, running, and customizing your Adobe Commerce storefront using the boilerplate.

Boilerplate version: 7.0.0

Terminology

Commerce drop-in components

Full-featured shopping components that turn websites into storefronts. Drop-in components are not primitive components, like Carousels and Galleries. They provide the entire storefront shopping experience for a website using pages and other commerce features.

Commerce blocks

The integration of Commerce drop-in components into the Edge Delivery Services architecture of JavaScript blocks and document-based authoring. Commerce blocks are the components that provide the content and layout for commerce pages in the storefront.

Content blocks

The Edge Delivery components that provide the content and layout for non-commerce pages in the storefront. These include Cards, Columns, Headers, Footers, and many more. Visit the Adobe Experience Manager Block Collection section for the details.

Creating your storefront

To create a new storefront from the boilerplate, you have two options:

Use the Site Creator Tool (Recommended) Visit the Site Creator Tool to quickly set up your own copy of code and content.
Follow the step-by-step guide See Create a storefront for a detailed walkthrough of using the GitHub template and configuring your environment.

Running locally

Once you have your storefront repository on your local machine:

1
npm install    # Install dependencies
2
npm start      # Start local development server

Your storefront will be running at http://localhost:3000.

Exploring the code

The boilerplate is organized into these main directories:

Directory	Purpose
blocks/	Commerce & content blocks plus standard AEM blocks (header, footer, cards, and so on)
scripts/	Core functionality - Drop-in initializers, commerce utilities, and Edge Delivery Services runtime
styles/	Global styles - Design tokens, fonts, and deferred styles for performance
tools/	Development tools - PDP metadata generator

Understanding the flow

To understand how documents transform into rendered commerce experiences at runtime, see the Runtime flow section in the architecture guide. This foundational knowledge helps you know where to customize and integrate with the boilerplate.

Customizing your storefront

Brand styling - Edit styles/styles.css for design tokens.
Block behavior - Modify block decorators in blocks/.
Commerce config - Update initializers in scripts/initializers/.
Add/remove blocks - Use only the Commerce blocks you need.

Customization strategy

Everything in the boilerplate can be modified. The guidance below is not about permission; it is about keeping your fork easy to maintain as the upstream boilerplate evolves.

Some files must not be edited:

scripts/aem.js — The core AEM runtime. Pulled verbatim from the upstream AEM Boilerplate; any local edit will conflict on the next sync.
package.json lifecycle scripts (postinstall, postupdate, install:dropins) — These run automatically during npm install to install and configure drop-ins. Changing them will break drop-in installation.

When customizing blocks or initializers, extract your changes to new files rather than editing existing ones. For example, you can add slot customizations to a new blocks/commerce-cart/slots.js and import it at the top of commerce-cart.js. Your customizations stay in a file you own, so when a boilerplate update arrives your changes to the original file are minimal — an import and a small usage change — rather than custom code scattered throughout it.

Layer	Strategy
`styles/`	Change colors, fonts, spacing, and layout here. Tokens in `styles/styles.css` apply across the whole site.
`blocks/`	Edit block appearance and behavior. Keep block folder names unchanged — authors reference them by name in documents.
`scripts/initializers/`	Configure each drop-in’s API endpoint and UI labels — one file per drop-in (for example, `cart.js`, `checkout.js`). If you remove a drop-in, also remove its initializer file and all imports of it in the codebase. See Using drop-ins.
`scripts/commerce.js`	Edit this file to add Commerce-specific logic such as consent handling (`getConsent`) or custom page type detection. It reads your storefront configuration and sets up Commerce API connections on every page.
`scripts/scripts.js`	Add auto-generated blocks to `buildAutoBlocks` (the boilerplate uses this for the hero block). Load third-party scripts, tag managers, or analytics tools in `scripts/delayed.js` — it runs 3 seconds after page load so they don’t affect initial render performance.
`build.mjs`	Edit this file to customize what data drop-ins fetch from Commerce. For example, you can add a custom product field to the PDP query or skip query fragments your project doesn’t need. Use the existing entries as patterns. Changes take effect after running `npm install`.

Deploying your storefront

Edge Delivery Services automatically builds and deploys when you push changes:

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

No manual build step is required—JavaScript bundling, CSS optimization, and asset compression happen automatically.

Keeping your storefront current

Track changes via the Boilerplate Changelog and Release notes. For complete guidance on upgrading drop-in components, applying updates, and handling breaking changes, see the Updates guide.

Resource	Description
Boilerplate Reference	Complete technical documentation - All blocks, configuration options, and file structure
Drop-in Components	API reference for each drop-in component
Commerce Blocks Guide	Business user guide for using blocks