Update the boilerplate

Upgrade your Adobe Commerce storefront to get the latest features, security updates, and performance improvements from the Commerce Boilerplate.

Overview

When you initially scaffold your Commerce storefront from the Commerce Boilerplate, you create a snapshot of the boilerplate at that point in time. As Adobe continues to improve the boilerplate with new features, bug fixes, and performance optimizations, your existing project won’t automatically receive these updates.

Note

If you created your project by forking the Commerce Boilerplate repository (rather than using the “generate from template” or site creator approach), you may have an easier upgrade path since you can leverage Git’s merge capabilities to pull upstream changes.

This guide shows you how to upgrade your storefront while preserving your customizations.

Vocabulary

Drop-in components

NPM packages containing the core Commerce functionality such as cart, checkout, product details, and user authentication.

Integration layer

Storefront-level files that integrate drop-ins with your site, including initialization scripts and block implementations.

Upstream

The original Commerce Boilerplate repository from which your project was created.

Selective updates

The process of manually choosing and merging specific changes from the upstream boilerplate into your project.

Breaking changes

Updates that require modifications to your existing code, typically found in major version releases.

Post-install scripts

Automated scripts that run after NPM package installation to copy updated Commerce logic to your local project.

Understanding the upgrade landscape

Upgrading is ongoing, not a one-time task. Regular, small updates are generally safer and easier to manage than infrequent, large upgrades.

What gets updated

Most of your storefront’s critical Commerce logic is now delivered through NPM packages, making upgrades significantly easier and more reliable. Upgrades typically involve these main areas:

Drop-in components: NPM packages containing the core Commerce functionality, including the following:

• @dropins/storefront-account
• @dropins/storefront-auth
• @dropins/storefront-cart
• @dropins/storefront-checkout
• @dropins/storefront-order
• @dropins/storefront-payment-services
• @dropins/storefront-pdp
• @dropins/storefront-personalization
• @dropins/storefront-product-discovery
• @dropins/storefront-recommendations
• @dropins/storefront-wishlist
• @dropins/tools

Boilerplate Integration Layer: storefront-level files that integrate drop-ins

File	Purpose	Update Frequency	Typical Changes
blocks/*	Block integration folders	Frequent	Drop-in integration JS and CSS. Rare updates to non-drop-in block examples (cards, accordion, etc) sourced from other boilerplates
scripts/aem.js	Core AEM functionality	Very Rare	Core platform improvements
scripts/commerce.js	Commerce-specific integration and utilities	Rare	Integration improvements, new utility functions
scripts/initializers/*	Drop-in initialization scripts	Moderate	New drop-in integrations, configuration updates
scripts/scripts.js	Page loading, block decoration, and global site functionality	Very Rare	Performance optimizations, new global features

Why upgrades are now easier

The Commerce Boilerplate team moved most of the complex Commerce logic into NPM-distributed drop-in packages, providing key advantages:

• Most logic is packaged: Core Commerce functionality, business rules, and complex state management are delivered through NPM packages
• Simplified storefront code: Your project primarily contains integration code, styling, and configuration
• Standard NPM upgrades: Most updates can be applied using standard npm install commands
• Reduced conflicts: Fewer files in your project means fewer merge conflicts when updating
• Consistent behavior: All storefronts benefit from the same tested, optimized Commerce logic

Upgrade strategies

NPM package updates

Recommended for most cases

Most Commerce logic lives in NPM packages, so this approach handles upgrades with minimal risk.

Step 1: Update drop-in components

Most of your Commerce functionality improvements come through these package updates:

Check your current versions:

npm list @dropins/storefront-*

Update individual components:

npm install @dropins/storefront-cart@latest
npm install @dropins/storefront-checkout@latest
# Repeat for other components as needed

Or update all drop-in components at once:

npm update @dropins/storefront-*

Note

The boilerplate’s postinstall and postupdate scripts automatically copy updated Commerce logic from node_modules to scripts/__dropins__ for Edge Delivery Services.

Step 2: Test your storefront

Since most logic changes are packaged, testing focuses on integration points:

Start your local development environment:

npm start

Test all Commerce functionality:

• Product detail pages
• Shopping cart operations
• Checkout flow
• User account features
• Search and navigation

Review the release notes for any integration changes that may affect your implementation.

For Major Version Updates

When upgrading drop-in packages across major versions (for example, from 1.x to 2.x), perform more thorough testing as these updates may include breaking changes. Pay particular attention to:

• Any custom integrations you’ve built around the drop-in components
• API interfaces you’re using
• Configuration settings that may have changed
• Custom styling or event handlers you’ve added

Test edge cases and error scenarios in addition to the standard user flows.

To help automate this testing process, consider implementing end-to-end testing in your project using tools like Cypress. These tools can simulate real user interactions across your Commerce flows, automatically catching regressions that manual testing might miss. Focus your automated tests on critical user journeys like product browsing, cart management, and checkout completion.

Note

Most Commerce logic updates require no additional code changes to your storefront because the complex functionality is delivered through the NPM packages.

Selective boilerplate updates

When you need integration layer improvements or new features that require changes to your storefront’s integration code, selectively merge changes from the upstream boilerplate repository.

1. Set up upstream remote

   Add the boilerplate repository as an upstream remote:

   git remote add upstream https://github.com/hlxsites/aem-boilerplate-commerce.git
   git fetch upstream

2. Review available updates

   Compare your current branch with the latest boilerplate to understand what changes are available.

   For detailed instructions on reviewing upstream changes, see GitHub's guide on syncing a fork and comparing commits .

   Focus your review on key files like scripts/commerce.js and the scripts/initializers/ directory where most Commerce-specific updates occur.

3. Identify changes to include

   Focus on these integration layer improvements:

   Commerce Integration Layer (scripts/commerce.js)

   • Enhanced drop-in initialization patterns
   • New configuration utilities
   • Performance optimizations
   • Bug fixes in integration logic

   Initializers (scripts/initializers/)

   • Updated drop-in initialization patterns
   • New feature integrations
   • Improved error handling

   Block Integration Updates (blocks/ directory)

   • Enhanced drop-in integration patterns
   • Accessibility improvements
   • Bug fixes in block-level integration

   Tip

   Each Commerce block now includes a README file that describes the block’s purpose and functionality. These README files are particularly helpful when diffing changes, as they provide a summary of what has changed in the block before you examine the code.

   Note

   Since most complex Commerce logic is now in NPM packages, boilerplate updates typically involve integration layer improvements rather than core functionality changes.

4. Apply selected changes

   Create a branch for your upgrade work to isolate changes and test before merging to main. Use a descriptive name indicating the upgrade with a timeframe or version (e.g., upgrade-august-2025 or upgrade-cart-v2.1.0).

   Once you’re on your upgrade branch, you have several options for applying changes from the upstream boilerplate:

   • Selectively merge individual files or directories that have updates you want to incorporate. This approach works well when you want to adopt specific improvements without bringing in changes that might conflict with your customizations.
   • Cherry-pick specific commits from the upstream repository if you want to apply only particular features or fixes. This gives you granular control over what changes to include and helps avoid introducing unwanted modifications.

   For each change you apply, commit it with a clear message describing what upstream improvement you’re incorporating. This creates a clean history that makes it easy to understand what was updated and why, which will be valuable for future upgrades and troubleshooting.

5. Resolve integration points and test

   • Resolve any conflicts in integration code, preserving your customizations
   • Test thoroughly in your development environment
   • Run your test suite if available
   • Deploy to a staging environment for comprehensive testing

Special considerations for early-adopter projects

Caution

If you scaffolded your project before mid-2025, you may have encountered a major architectural change: Commerce logic moved from scripts.js to scripts/commerce.js. This shift affects your update scope but uses the same methods above.

Understanding the architectural change

The major refactoring (PR #567) reorganized the boilerplate architecture with two significant improvements:

1. Separation of AEM and Commerce logic:

• scripts/scripts.js - Core AEM functionality, aligned with the upstream AEM Boilerplate
• scripts/commerce.js - Commerce-specific integration and utility logic

2. Core Commerce logic migration to NPM packages:

• Complex Commerce functionality moved to @dropins/tools and other drop-in packages
• Functions previously embedded in your integration code are now abstracted to reusable, versioned, and upgradable libraries
• The Commerce Boilerplate is now focused on pure integration code that you own

Before the refactoring: In early versions of the Commerce Boilerplate, all logic lived in scripts/scripts.js where Commerce business logic was mixed with integration code. Core Commerce functions were embedded directly in your project files, making it difficult to upgrade Commerce functionality without encountering code conflicts during merges.

After the refactoring: The architecture now separates concerns more effectively. Core Commerce logic lives in NPM packages that are easily upgradable, while the boilerplate contains minimal integration code that results in fewer merge conflicts. This creates clear boundaries between platform logic and your customizations, allowing future updates to focus on integration patterns rather than business logic.

This architectural shift means that complex Commerce operations, utility functions, and business rules that you may have seen in your early boilerplate files are now delivered through NPM packages, making them upgradable without touching your project code.

Adapting your update approach

If you have an early-adopter project, your updates will need a broader scope to account for architectural changes.

When reviewing updates, pay attention to the main scripts file (scripts/scripts.js) and the Commerce integration layer (scripts/commerce.js). Both have changed significantly. Be sure to preserve your custom business logic while adopting the improved structural foundation that the upstream changes provide.

The migration process requires more careful consideration than typical updates since you’re not just incorporating new features, but potentially restructuring how your existing customizations integrate with the boilerplate’s core functionality.

During Step 4 (apply selective changes), you may need to migrate your customizations:

Custom functions in the “old” scripts/scripts.js

• Commerce-related customizations should move to scripts/commerce.js
• General AEM functionality should remain in scripts/scripts.js
• Many custom functions may now be available as utilities in @dropins/tools

Block import updates

• Update imports from ../../scripts/scripts.js to ../../scripts/commerce.js for Commerce utilities
• Verify that custom utilities are still available or replace with package utilities

Integration pattern updates

• Review if custom functions can be replaced with utilities from @dropins/tools package
• Update integrations to use new patterns for Commerce-specific functionality

During Step 5 (testing), pay special attention to:

• Custom blocks that import Commerce utilities
• Third-party integrations that depend on Commerce functions
• Custom analytics implementations that hook into Commerce events
• Any custom business logic that was mixed with platform code

Benefits of architectural alignment

While early-adopter projects require more comprehensive selective updates, aligning with the new architecture provides significant long-term benefits:

• Future updates simplified: Once aligned, future updates will be much easier due to reduced code surface area
• Better separation of concerns: Clear boundaries between platform logic and your customizations
• Reduced merge conflicts: Commerce functionality updates through NPM packages instead of file merges
• Access to latest features: Full compatibility with new drop-in components and features
• Enhanced PDP flexibility: Container-based PDP architecture provides unprecedented customization control

Product details page architectural evolution

Note

If your project was scaffolded from early versions of the Commerce Boilerplate before November 27, 2024, the PDP drop-in itself underwent a major evolution from a single-container approach to a fully composable, multi-container architecture. Projects with the slot-based architecture should consider migrating to the container-based approach for better long-term maintainability.

Previous architecture (slot-based customization)

Early versions of @dropins/storefront-pdp used a single ProductDetails container with predefined slots. You could customize by:

• Creating custom slot implementations for different sections of the page
• Working within the constraints of the single-container structure
• Limited ability to rearrange or completely replace sections of the PDP
• Complex styling workarounds to achieve desired layouts

New architecture (container-based composition)

The latest version breaks down the PDP into independent containers you can compose, style, and replace:

• ProductHeader - Product title, SKU, and basic information
• ProductPrice - Pricing display and special price handling
• ProductGallery - Image carousel with flexible configuration
• ProductOptions - Product variants and configuration
• ProductQuantity - Quantity selector
• ProductDescription - Product descriptions and content
• ProductAttributes - Product specifications and metadata

For detailed information about the container-based architecture and implementation patterns, see the Product Details Drop-in Documentation. You can also reference the current product-details block implementation in the Commerce Boilerplate for practical examples of the container-based approach.

Migration benefits for PDP blocks

• Complete layout control: Arrange containers in any order within your block structure
• Individual container replacement: Replace entire sections (like gallery or pricing) with custom implementations
• Simplified styling: Style containers independently without complex CSS overrides
• Enhanced functionality: Each container can be configured independently with specific features
• Eliminated slot workarounds: UI customizations that required appending, prepending, or replacing slot content can now be handled directly in the layout structure or by completely replacing containers
• Direct data access: Product data previously available through slot context is now accessible via the event bus (pdp/data and pdp/values)
• Future-proof architecture: New PDP features delivered as new containers rather than slot modifications

PDP block migration process

When updating your PDP block from slot-based to container-based:

1. Update dependencies

// Old: Single container with slots
import { ProductDetails } from '@dropins/storefront-pdp/containers/ProductDetails.js';

// New: Multiple independent containers
import ProductHeader from '@dropins/storefront-pdp/containers/ProductHeader.js';
import ProductPrice from '@dropins/storefront-pdp/containers/ProductPrice.js';
import ProductGallery from '@dropins/storefront-pdp/containers/ProductGallery.js';
// ... other containers

2. Replace slot implementations

You can often remove custom slot implementations entirely—the new containers provide better configuration.

3. Update block structure

Replace the single container render with multiple container renders:

// Old: Single render with slot configuration
await productRenderer.render(ProductDetails, {
  slots: {
    Title: (ctx) => Title(ctx, block),
    Options: (ctx) => Options(ctx, block),
    // ... other slots
  }
})(block);

// New: Multiple container renders
await pdpRendered.render(ProductHeader, {})($header);
await pdpRendered.render(ProductPrice, {})($price);
await pdpRendered.render(ProductGallery, { controls: 'thumbnailsColumn' })($gallery);
// ... other containers

4. Layout restructuring

Create HTML structure that positions containers where you need them:

<div class="product-details__wrapper">
  <div class="product-details__header"></div>
  <div class="product-details__price"></div>
  <div class="product-details__gallery"></div>
  <!-- Full control over container placement -->
</div>

5. Styling migration

• Remove complex CSS overrides targeting internal slot structures
• Style containers directly with cleaner, more maintainable CSS
• Review any potential class name changes between architectures
• Handle breakpoints and responsive layout at the block level, as this is now the block’s responsibility

Tracking updates

Monitor boilerplate changes

Stay informed about boilerplate updates:

• GitHub watch: Watch the Commerce Boilerplate repository for releases and important changes
• Changelog tracking: Follow issues tagged with the changelog label
• Release notes: Review drop-in component release notes at the Release Information page

Version management best practices

Document your customizations

• Document all customizations
• Write clear commit messages
• Tag storefront releases

Establish update cadence

• Review updates monthly or quarterly
• Schedule major upgrades for low-traffic periods
• Test in staging

Troubleshooting common issues

Post-install script failures

If post-install fails:

• Check Node.js and NPM version compatibility
• Clear NPM cache: npm cache clean --force
• Remove and reinstall: rm -rf node_modules package-lock.json && npm install
• Check file permissions

Merge conflicts

When merging updates:

• Understand the context: Review both versions
• Preserve functionality: Keep your customizations working
• Test thoroughly: Conflicts signal significant changes
• Be selective: Only merge valuable updates; avoid bringing in features you won’t use

Breaking changes

When drop-in updates introduce breaking changes:

• Review migration guides: Check package release notes for migration instructions
• Update integrations: Modify custom code that depends on changed APIs
• Test edge cases: Breaking changes often affect less common use cases
• Plan rollback: Have a rollback plan ready before applying breaking changes

Best practices

Development workflow

Branch strategy

• Create upgrade branches with descriptive names (e.g., upgrade-cart-v2.1.0)
• Merge upgrades through pull requests with thorough reviews

Testing approach

• Cover custom functionality with tests
• Automate testing where possible
• Test across devices and browsers
• Use real product data

Deployment process

• Use staging environments that mirror production
• Deploy during low-traffic periods
• Monitor key metrics post-deployment
• Have rollback procedures ready

Long-term maintenance

Stay current

• Update regularly, don’t let them pile up
• Apply security patches promptly
• Plan major upgrades ahead well in advance

Customize thoughtfully

• Minimize modifications to core boilerplate files
• Use configuration and theming approaches when possible
• Document the business justification for customizations

Resources

• Storefront Developer Tutorial: Comprehensive storefront setup guide
• Architecture Guide: Understanding the technical foundation
• Drop-in Components Documentation: Detailed component guides
• AEM Edge Delivery Services : Core platform documentation
• Commerce Boilerplate Repository : Source code and latest updates
• Release Notes: Track major changes and updates
• Boilerplate Releases : GitHub releases and version history