Commerce Boilerplate

Getting started

This page helps you run, examine, and customize a storefront that already uses the Commerce boilerplate. By the end, you’ll know where the main files live and which files are safest to customize.

Key terms

The boilerplate uses Drop-in components for shopping features such as cart, checkout, product details, and requisition lists when you serve business buyers. It connects those features to document-authored pages with Commerce blocks. For general content and layout, it uses Content blocks such as cards, columns, headers, and footers.

For more information about standard Edge Delivery blocks, see the Adobe Experience Manager Block Collection .

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. The create-a-storefront topic links here for npm install and npm start so those instructions stay in one place.

Install the project dependencies.
```
1
npm install
```
Start the local development server.
```
1
npm start
```
Open http://localhost:3000 in your browser.

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

**Optional: **install the aem command globally with npm install -g @adobe/aem-cli if you want to run the CLI from any directory. The boilerplate already lists @adobe/aem-cli as a dev dependency, so after npm install the npm start script can run without a global install.

Key runtime packages

After npm install, package.json resolves many dependencies. You do not need to memorize them on day one. 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

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.

1
aem-boilerplate-commerce/
2
├── blocks/                 # Commerce blocks, content blocks, and standard AEM blocks
3
├── scripts/
4
│   ├── scripts.js           # page load orchestration (eager, lazy, delayed)
5
│   ├── commerce.js        # Commerce loading, templates, storefront configuration
6
│   └── initializers/      # one initializer file per drop-in (endpoints, labels, and related settings)
7
├── styles/                 # global CSS, tokens, fonts, deferred styles
8
├── tools/                  # dev helpers (for example, PDP metadata tooling)
9
├── config.json             # storefront endpoints, locale, and related settings
10
└── package.json            # dependencies, scripts, and drop-in install hooks

Directory	Purpose
blocks/	Contains Commerce blocks, content blocks, and standard AEM blocks such as header, footer, and cards.
scripts/	Contains drop-in initializers, Commerce utilities, and the Edge Delivery Services runtime.
styles/	Contains global styles, design tokens, fonts, and deferred styles for performance.
tools/	Contains development tools such as the product detail page (PDP) metadata tool.

Understanding the flow

To understand how documents become rendered commerce experiences at runtime, see How a page loads in Storefront architecture. This overview helps you decide where to customize and where to leave boilerplate files unchanged.

Customizing your storefront

Brand styling: edit styles/styles.css for design tokens.
Block behavior: modify block decorators in blocks/.
Commerce configuration: update initializers in scripts/initializers/.
Commerce blocks: use only the blocks your storefront needs.

Customization strategy

Most files in the boilerplate can be modified. The guidance below helps keep your storefront project easy to maintain as the original boilerplate repository evolves.

Files to keep unchanged

scripts/aem.js: The core AEM runtime. This file comes from the original AEM Boilerplate . Local edits can conflict with future boilerplate updates.
package.json lifecycle scripts (postinstall, postupdate, install:dropins): These scripts run during npm install to install and configure drop-ins. Changing them can break drop-in installation.

The table below lists the usual layers you change for branding, blocks, Commerce wiring, page scripts, and build-time queries. Order follows a common path: global styles and blocks first, then initializer and script layers, then build.mjs for query shaping.

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 because authors reference them by name in documents.
`scripts/initializers/`	Configure the API endpoint and UI labels for each drop-in. Each drop-in has one initializer file, such as `cart.js` or `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 automatically 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`. That file runs 3 seconds after page load so these scripts do not affect the initial page render.
`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`.

When to customize

When you customize blocks or initializers, put project-specific code in new files when possible. For example, you can add slot customizations to a new blocks/commerce-cart/slots.js file and import it at the top of commerce-cart.js. Your customizations stay in a file you own. When a boilerplate update arrives, your changes to the original file stay small.

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.

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.

Resource	Description
Boilerplate reference	Technical documentation for blocks, configuration options, and file structure.
Drop-in components	API reference for each drop-in component.
Commerce blocks page	Business user page for using blocks.