How to switch your AEM Client Library to Proxy Mode
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
- 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
andpublish
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
- If you have both publish-related and author-related clientlibs, it is recommend to create additional subfolders named
- 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
- 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 thecomplete
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
- This can be done by adding the old location path e.g. to the
- 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 theresources
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
- If your are embedding other client libraries, it is recommended to set the flag
- 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. - 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.
- Make sure CSS source files contain only relative references to their own
- 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.0io.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
- you should update to at least this versions (or the latest version) of:
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