Upgrading the aem.js boilerplate in Adobe Experience Manager as a Cloud Service

Last update: October 23, 2026

This article provides guidance for upgrading the aem.js boilerplate in Adobe Experience Manager as a Cloud Service, highlighting compatibility considerations, workflow impacts, and recommended best practices.

Description description

Environment

Adobe Experience Manager as a Cloud Service (all versions), aem.js boilerplate v3.0.0–v3.1.8

Issue/Symptoms

You want to incorporate upstream changes to aem.js in an existing project.
You need to check the effects on custom blocks, scripts, preview, or publishing before merging the changes.

Cause

The AEM boilerplate is a starter project. Changes to the upstream boilerplate do not update an existing project automatically; developers review and integrate the changes into their project repository. Project-specific behavior belongs in extensions outside aem.js, not in local modifications to the library.

Resolution resolution

Follow the steps below to resolve the issue:

Review the changes introduced in the aem.js boilerplate between versions 3.0.0 and 3.1.8.
Verify whether your implementation uses version 3.1.0. This release introduced a breaking change that removed section metadata handling from decorateSections(). The change was identified as a regression and was reverted in version 3.1.1.
If your implementation uses version 3.1.0, upgrade to version 3.1.1 or later to restore section metadata handling.
Review the changes introduced in versions 3.1.1 through 3.1.8. These releases include dependency updates and minor fixes, such as resolving duplicate header and footer blocks and updating code path resolution.
Assess the impact on your implementation and verify that no breaking changes affect publishing, preview, or block-rendering workflows. Apart from the regression in version 3.1.0, no breaking changes were identified in these workflows.
Validate changes in a feature branch before upgrading. Configure the branch to use a preview environment and review the changes after pushing the updated code.

Test the changes locally before publishing them. Use the AEM CLI to retrieve content and validate updates. The following commands can help you review changes before publishing:

code language-none
`aem content clone aem up aem content diff aem content push --dry-run`

Configure branch protection rules for the main branch and require pull requests, status checks, and up-to-date branches before merging changes. This helps ensure that all changes are reviewed and validated in a preview environment before reaching production.
After upgrading, thoroughly test custom blocks and script dependencies in both local and preview environments to verify compatibility.
Verify that publishing, preview, block rendering, section metadata handling, custom blocks, and script dependencies function as expected after the upgrade.

recommendation-more-help

experience-cloud-kcs-help-kbarticles