How to upgrade /apps overlays out-of-the-box source files


When upgrading AEM, most customizations that are overlaid from /libs folder to /apps might not work after upgrade.  Those customizations might even break out of the box functionality after upgrading.  To solve this situation we follow the steps below to migrate our customizations to the newer version of AEM.


  1. On your current (non-upgraded) AEM environment, go to http://aem-host:port/crx/packmgr/index.jsp and log in as an administrative user

  2. Create a package containing all your overlays under /apps folder and the corresponding /libs files.  For example, if you have overlaid /libs/cq/ui/widgets/source/widgets/wcm/SiteAdmin.Actions.js under /apps/cq/ui/widgets/source/widgets/wcm/SiteAdmin.Actions.js then you would include both of those paths in the package.

  3. Download the package

  4. Unzip the contents of the package locally

  5. Download a diff tool on your machine.  On Windows you can use WinMerge and on Mac or Linux you can use KDiff3.

  6. Install the diff tool

  7. Use the diff tool to diff the jcr_root/apps and the jcr_root/libs folder extracted from the zip in step 4

  8. Use this diff to review your old customizations you had made when overlaying the out of the box files

  9. On your local machine, install a clean instance of the version of AEM you intend to upgrade to

  10. Go to http://aem-host:port/crx/packmgr/index.jsp on the new instance

  11. Create a package of your same overlay /libs locations from the newer version of AEM

  12. Download the package

  13. Unzip the contents of the package

  14. Use the diff and the files extracted from the newer AEM version to "upgrade" or re-implement your customizations