Overview

Since AEM 6.1 Adobe recommends to not longer place the AEM Client Libraries below /etc/clientlibs or /etc/designs, but to place them below /apps and set allowProxy=true on it (see AEM documentation).

On the publish side there is usually no direct access to /apps possible, thus the clientlibs are services using a proxy service via the URL /etc.clientlibs (note the dot instead of the slash).

This article describes how to switch your AEM Client Library to this proxy mode, with a focus on applications based on the wcm.io stack.

Instructions

Steps to switch an AEM Client Library to Proxy Mode

1. Move the Client Library in your AEM project to a folder below /apps/<yourapp>/clientlibs
   
   • If you have both publish-related and author-related clientlibs, it is recommend to create additional subfolders named author and publish below this folder
   • If you deploy your client lib via an OSGi bundle an Sling-Initial-Content: Update the paths in the Sling-Initial-Content instruction in the POM as well
   • If you are using an AEM package: Update the path in the filter.xml of the package as well
   • If you are using a NodeJS-based frontend build with aem-clientlib-generator update the destination paths in the package.json
2. Check all client libraries and make sure all static resources (e.g. web fonts, images) are within a resources folder of the client library
   • If this is not the case, introduce such a folder, move the static resource to it, and update all references to the static static resources
3. Make sure the older client library folder is removed from instances where you application was already installed before with the old location
   • This can be done by adding the old location path e.g. to the filter.xml of the complete AEM package, without any content behind it.
   • If you forget this AEM may load both your new and old clientlibs in the same page, creating problems when your client library evolves
4. Set the flag allowProxy=true on your client library
   • If your are embedding other client libraries, it is recommended to set the flag allowProxy=true on all of them as well - otherwise static files from the resources folder of the embedded libraries will not be available on publish
   • If you are using a NodeJS-based frontend build with aem-clientlib-generator you may need to set the flag in the package.json or js configuration file and re-generate the client libraries
5. If you are using the build-helper-maven-plugin to generate populate the longCacheKey property with the current project version/build number of your project, make sure to update the path to the client library for this in the POM as well.
6. Search all of your source code files (esp. HTL, JSP files, Java files) for reference to the old client library path below /etc and switch it to the new path below /apps.
   • Make sure CSS source files contain only relative references to their own resources folder, and do not use full paths
   • JS source files should not contain any full path references to static resources. It's better to put the path in the markup and get them from there, or make them otherwise configurable.
7. If you are using wcm.io Handler:
   • you should update to at least this versions (or the latest version) of:
     • io.wcm.handler.url 1.3.0
     • io.wcm.testing.wcm-io-mock.handler 1.1.0
   • Make sure a service user mapping is configured for io.wcm.handler.url (new since 1.3.0) - see https://wcm.io/handler/url/configuration.html
   • Make sure the Sling Rewriter Integration for the URL handler is in place - see https://wcm.io/handler/url/rewriter.html

With this in place:

• All client libraries should be available on author and publish the need to change any ACLs
• All client libraries are served via the URL /etc.clientlibs
• All direct references to any static resources from HTL/JSP files or Java files are automatically rewritten by the wcm.io URL handler to the proxy location at /etc.clientlibs

Related articles

The content by label feature displays related articles automatically, based on labels you choose. To edit options for this feature, select the placeholder below and tap the pencil icon.