Edge Delivery Services with AEM Authoring Boilerplate for Commerce

This project boilerplate is for AEM Authoring with Edge Delivery Services (aka Crosswalk) projects that integrate with Adobe Commerce.

Note

Using Edge Delivery with AEM Authoring for Commerce is meant for customer that cannot adapt Experience Workspace, the documented default for Adobe Commerce Storefront. If you think you need to use this Boilerplate please get in touch with us.

Documentation

Before using the boilerplate, we recommend you to go through the documentation on https://experienceleague.adobe.com/developer/commerce/storefront/ and more specifically:

1. Storefront Developer Tutorial
2. AEM Docs
3. AEM Developer Tutorial
4. The Anatomy of an AEM Project
5. Web Performance
6. Markup, Sections, Blocks, and Auto Blocking

See Sync and Release for the developer workflow.

Getting Started

Use the Site Creator Tool to quickly spin up your own copy of code and content.

Alternatively, you can follow our Guide for a more detailed walkthrough.

Installation

Install dependencies and explicitly activate the Git hooks:

npm install
npm run prepare

npm run prepare installs this repository's Husky hooks, including automatic component JSON generation when partial models are committed. It must be run explicitly because ignore-scripts=true also skips automatic prepare execution. Dependency lifecycle scripts remain disabled.

This repo's .npmrc sets ignore-scripts=true, which disables npm lifecycle scripts (preinstall/install/postinstall) for every package. This is a defense against npm supply-chain attacks that hide malicious code inside those scripts. One consequence is that npm install alone will not copy the drop-in assets into scripts/__dropins__ or apply the GraphQL overrides defined in build.mjs.

After every npm install — initial setup, or any time a @dropins/* or @adobe/* dependency changes — run:

npm run install:dropins

This copies the built assets from node_modules/@dropins and the relevant @adobe/* packages into scripts/__dropins__, and applies the GraphQL fragment/operation overrides in build.mjs. Edge Delivery Services serves the copied files directly, so this step must complete before npm start will reflect the correct drop-in behavior.

Staying Up to Date

Once you fork or clone this repo, the code is yours — you are not subscribed to updates.

What a suite release is (and is not)

A suite release — for example "b2c-march-2026" — is a tagged snapshot of this boilerplate at a point in time when a specific combination of drop-in package versions and boilerplate code was tested together and verified to work. That tag is useful as a starting point for developers who are setting up a new project. You can find the release notes for each suite release in the releases page.

If you have already forked or cloned this repo, a new suite release is not an upgrade you need to apply. There is no mechanism that pushes boilerplate code changes into your fork, and nothing will break in your project because a new release tag was created upstream. Treat suite releases the same way you would treat a new major version of a project template: relevant only if you are starting fresh.

Updating your drop-in dependencies

The only things you need to actively track after forking are your npm dependencies — specifically the @dropins/* and @adobe/* packages (including @adobe/magento-storefront-event-collector and @adobe/magento-storefront-events-sdk) listed in your package.json. Before applying any update, check the release notes for breaking changes and ensure you run npm run install:dropins so that the dependencies in your scripts/__dropins__ directory are updated to the latest build.

These packages follow semantic versioning. Minor and patch releases are non-breaking by contract, so routine updates should be safe to apply.

To see which packages have newer versions available:

npm outdated

To install a specific version:

npm install @dropins/storefront-cart@2.0.0  # updates the package in node_modules/
npm run install:dropins                     # copies scripts from node_modules into scripts/__dropins__/

To update a drop-in to its latest stable release:

npm install @dropins/storefront-cart@latest
npm run install:dropins

Always run npm run install:dropins after any drop-in update — it copies the built assets from node_modules into scripts/__dropins__, which is what Edge Delivery Services serves. Since this repo disables npm lifecycle scripts (see Installation), this step is never run automatically and must always be done manually.

Automated dependency PRs

This repo includes a GitHub Actions workflow (.github/workflows/update-dependencies.yaml) that runs every Monday and opens a pull request when newer stable versions of @adobe/* or @dropins/* packages are available within the ranges declared in your package.json (semver). The PR includes updated package.json, package-lock.json, and regenerated dropin assets under scripts/__dropins__/. Pre-release packages are held without changes and surfaced in the workflow output. This works similarly to Dependabot or Renovate; once you fork the repo, the workflow runs in your fork so you can review and merge updates at your own pace.

Enabling it on your fork/clone

Whether this works out of the box depends on your organization's (or personal account's) default policy for the "Allow GitHub Actions to create and approve pull requests" setting — some orgs disable it by default for new repositories. If it's off, the workflow will run "successfully" (it updates package.json locally) but silently fail to open the PR, with no obvious error in the run logs. If your fork doesn't get a PR after the workflow runs, check and enable this setting:

1. In your fork/clone, go to Settings → Actions → General.
2. Scroll to Workflow permissions.
3. Ensure Read and write permissions is selected.
4. Check Allow GitHub Actions to create and approve pull requests.
5. Click Save.

Then verify it works by triggering it manually: go to the Actions tab, select Update Dependencies in the sidebar, and click Run workflow. Confirm a pull request is opened once the run completes (if there are no updates available, no PR will be created — bump a version range in package.json to force a test run if needed).

If your GitHub organization disallows the "Allow GitHub Actions to create and approve pull requests" setting at the org level and won't allow individual repos to override it, use a personal access token (PAT) or GitHub App token instead of the default GITHUB_TOKEN, which bypasses that restriction:

1. Create a fine-grained PAT (or a GitHub App installation token) with Contents: Read and write and Pull requests: Read and write permissions scoped to your repo.
2. Store it as a repository secret (e.g. DEPENDENCY_UPDATE_PAT) under Settings → Secrets and variables → Actions.
3. Update the token: input on the peter-evans/create-pull-request step in update-dependencies.yaml to reference that secret instead of ${{ secrets.GITHUB_TOKEN }}.

Pulling boilerplate code changes into your fork (optional)

If you want to incorporate code changes made to this upstream boilerplate after you forked — for example, a new block or a bug fix in scripts/ — you can do so by adding this repo as a git remote and merging selectively. This is entirely optional. Upstream changes may conflict with modifications you have made to your fork, so expect to resolve conflicts manually. There is no guarantee of a clean merge, and nothing in your project depends on staying in sync with the upstream boilerplate code.

Analytics loading

Following the upstream AEM consent gate, the Adobe Commerce event SDK and collector (scripts/consented.js) load only after consent is granted. Without consent they are not loaded.

• scripts/consent-check.js is a placeholder gate: ?consent=accept (also true, 1, yes) grants consent for the page load; anything else declines. It dispatches a consent.update event on window.
• The Adobe Client Data Layer (ACDL) keeps events and context in memory. Separately, custom code in scripts/commerce.js records product-view and purchase history in localStorage, independently of consent.
• The product-recommendations block can request contextual recommendations using the current product SKU without consent. It only reads and includes local histories in recommendation requests after consent. See the block README.

Behaviour	Without consent	After consent
ACDL events and context in memory	Active	Active
Recording local view/purchase history	Active	Active
Loading the analytics SDK and collector	Not loaded	Loaded if analytics is configured
Contextual recommendation requests	Available	Available
View/purchase history and cart SKUs in recommendation requests	Excluded	May be included

This gate is not a consent management platform (CMP). The query parameter is a testing placeholder, not a persisted preference. Merchants and implementation partners must replace it with their own CMP integration, connect the decision to consented script loading, and dispatch consent.update with { detail: { consented: true | false } } for consumers such as the recommendations block. The placeholder does not provide a complete revocation or data-deletion workflow.

Boilerplate's consent gate does not automatically integrate with Adobe Commerce Cookie Restriction Mode or manage mg_dnt. These are separate mechanisms and do not automatically control Boilerplate's custom local-history storage. See the block's integration guidance for the distinction and implementation responsibilities.

Changelog

Major changes to this boilerplate are described and documented as part of pull requests and tracked via the changelog tag. This log documents changes to the canonical starting point — not upgrades that forked implementations must apply. Review it if you are considering pulling specific upstream changes into your fork:

https://github.com/hlxsites/aem-boilerplate-commerce/issues?q=label%3Achangelog+is%3Aclosed

Product Detail Pages (PDPs)

Since Ocotober 2025, folder mapping is no longer configured by default as its deprecated. To keep it easy to start, static product pages have been created as part ot the site template for all products listed on the homepage.

It is highly recommended to create physical product detail pages in Edge Delivery Services. Use the AEM Commerce Prerenderer to implement a byom overaly that creates and publishes product detail pages from the product data available in Catalog Service.