Digital experiences rely heavily on client-side processing driven by complex JavaScript and CSS code. AEM Client-Side Libraries (clientlibs) allow you to organize and centrally store these client-side libraries within the repository. Coupled with the front-end build process in the AEM Project archetype, managing your front-end code for your AEM project becomes simple.
Advantages of using clientlibs in AEM include:
Clientlibs are the built-in solution for delivering CSS and Javascript from AEM.
Front-end developers who are creating CSS and Javascript for AEM projects should also familiarize themselves with the AEM Project Archetype and its automated front-end build process.
Sites require JavaScript and CSS as well as static resources such as icons and web fonts to be processed client-side. A clientlib is AEM’s mechanism to reference (by category if required) and serving such resources.
AEM collects the site’s CSS and Javascript into a single file, in a central location, to ensure that only one copy of any resource is included in the HTML output. This maximizes the efficiency of delivery and allows such resources to be maintained centrally in the repository via proxy, keeping access secure.
All JavaScript, CSS, and other front-end assets should be maintained in the ui.frontend module of the AEM Project Archetype. The flexibility of the archetype allows you to use your modern web tools of choice to create and manage these resources.
The archetype can then compile the resources into single CSS and JS files, embedding them automatically into a cq:clientLibraryFolder
in the repository.
A client-side library folder is a repository node of type cq:ClientLibraryFolder
. Its definition in CND notation is
[cq:ClientLibraryFolder] > sling:Folder
- dependencies (string) multiple
- categories (string) multiple
- embed (string) multiple
- channels (string) multiple
cq:ClientLibraryFolder
nodes can be placed anywhere within the /apps
subtree of the repository.categories
property of the node to identify the library categories to which it belongs.Each cq:ClientLibraryFolder
is populated with a set of JS and/or CSS files, along with a few supporting files (see below). Important properties of the cq:ClientLibraryFolder
are configured as follows:
allowProxy
: Since all clientlibs must be stored under apps
, this property allows access to clientlibraries ia proxy servlet. See Locating a Client Library Folder and Using the Proxy Client Libraries Servlet below.categories
: Identifies the categories into which the set of JS and/or CSS files within this cq:ClientLibraryFolder
fall. The categories
property, being multi-valued, allows a library folder to be part of more than one category (see below for how this may be useful).If the client library folder contains one or more source files that, at runtime, they are merged into a single JS and/or CSS file. The name of the generated file is the node name with either the .js
or .css
file name extension. For example, the library node named cq.jquery
results in the generated file named cq.jquery.js
or cq.jquery.css
.
Client library folders contain the following items:
js.txt
file and/or one css.txt
file which identify the source files to merge in the generated JS and/or CSS filesClient libraries must be located under /apps
. This is in order to better isolate code from content and configuration.
In order for the client libraries under /apps
to be accessible, a proxy servelt is used. The ACLs are still enforced on the client library folder, but the servlet allows for the content to be read via /etc.clientlibs/
if the allowProxy
property is set to true
.
https://<host>:<port>/crx/de
)./apps
folder and click Create > Create Node.cq:ClientLibraryFolder
. Click OK and then click Save All.cq:ClientLibraryFolder
node, add the following property, and then click Save All:
categories
/etc.clientlibs
, select the cq:ClientLibraryFolder
node, add the following property, and then click Save All:
allowProxy
true
resources
below the client library folder.
resources
, they can not be referenced on a publish instance.js.txt
: Use this file name to generate a JavaScript file.css.txt
: Use this file name to generate a Cascading Style Sheet.#base=*[root]*
[root]
with the path to the folder that contains the source files, relative to the TXT file. For example, use the following text when the source files are in the same folder as the TXT file:
#base=.
cq:ClientLibraryFolder
node:
#base=mobile
#base=[root]
, type the paths of the source files relative to the root. Place each file name on a separate line.Once your client library folder is configured as required, your clientlibs can be requested via proxy. As an example:
/apps/myproject/clientlibs/foo
/apps/myprojects/clientlibs/foo/resources/icon.png
The allowProxy
property allows you to request:
/etc.clientlibs/myprojects/clientlibs/foo.js
/etc.clientlibs/myprojects/clientlibs/foo/resources/icon.png
Once your clientlibs are successfully stored and managed in their client library folder, they can be access via HTL.
Client libraries are loaded through a helper template provided by AEM, which can be accessed through data-sly-use
. Helper templates are available in this file, which can be called through data-sly-call
.
Each helper template expects a categories
option for referencing the desired client libraries. That option can be either an array of string values, or a string containing a comma separated values list.
See the HTL documentation for more details on loading clientlibs via HTL.
Most clientlibs will be required on the AEM publish instance. That is, most clientlibs’ purposes are to produce the end-user experience of the content. For clientlibs on publish instances, front-end build tools can be used and deployed via client library folders as described above.
However there are times when client libraries may be necessary to customize the authoring experience. For example, customizing a dialog might require deploying small bits of CSS or JS to the AEM authoring instance.
If you need to use client libraries on author, you can create your client libraries under /apps
using the same methods as for publish, but write it directly under /apps/.../clientlibs/foo
instead of creating an entire project to manage it.
You can then “hook” into the authoring JS by adding your client libraries to an out-of-the-box client library category.
AEM provides several tools for debugging and testing client library folders.
The /libs/cq/granite/components/dumplibs/dumplibs
component generates a page of information about all client library folders on the system. The /libs/granite/ui/content/dumplibs
node has the component as a resource type. To open the page, use the following URL (changing the host and port as required):
https://<host>:<port>/libs/granite/ui/content/dumplibs.test.html
The information includes the library path and type (CSS or JS), and the values of the library attributes, such as categories and dependencies. Subsequent tables on the page show the libraries in each category and channel.
The dumplibs
component includes a test selector that displays the source code that is generated for ui:includeClientLib
tags. The page includes code for different combinations of js, css, and themed attributes.
dumplibs.html
page, click the link in the Click here for output testing text.http://<host>:<port>/libs/granite/ui/content/dumplibs.html
categories
property and click Submit Query.There are a number of other features that are supported by client library folders in AEM. However, these are not required on AEM as a Cloud Service and as such their use is discouraged. They are are listed here for completeness.
These additional features of Client Library Folders are not required on AEM as a Cloud Service and as such their use is discouraged. They are are listed here for completeness.
Additional client library settings can be controlled through the Adobe Granite HTML Library Manager panel of the System Console at https://<host>:<port>/system/console/configMgr
).
Additional folder properties include allow control of dependencies and embeds, but are generally no longer needed and their use is discouraged:
dependencies
: This is a list of other client library categories on which this library folder depends. For example, given two cq:ClientLibraryFolder
nodes F
and G
, if a file in F
requires another file in G
in order to function properly, then at least one of the categories
of G
should be among the dependencies
of F
.embed
: Used to embed code from other libraries. If node F
embeds nodes G
and H
, the resulting HTML will be a concatenation of content from nodes G
and H
.When the code in your client library folder references other libraries, identify the other libraries as dependencies. The ui:includeClientLib
tag that references your client library folder causes the HTML code to include a link to your generated library file as well as the dependencies.
The dependencies must be another cq:ClientLibraryFolder
. To identify dependencies, add a property to your cq:ClientLibraryFolder
node with the following attributes:
For example, the /etc/clientlibs/myclientlibs/publicmain
has a dependency on the cq.jquery
library. The page that references the main client library generates HTML that includes the following code:
<script src="/etc/clientlibs/foundation/cq.jquery.js" type="text/javascript">
<script src="/etc/clientlibs/mylibs/publicmain.js" type="text/javascript">
You can embed code from a client library into another client library. At runtime, the generated JS and CSS files of the embedding library includes the code of the embedded library.
Embedding code is useful for providing access to libraries that are stored in secured areas of the repository.
It is a best practice to keep all application-related files in their application folder below /app
. It is also a best practice to deny access for web site visitors to the /app
folder. To satisfy both best practices, create a client library folder below the /etc
folder that embeds the client library that is below /app
.
Use the categories property to identify the client library folder to embed. To embed the library, add a property to the embedding cq:ClientLibraryFolder
node, using the following property attributes:
cq:ClientLibraryFolder
node to embed.In some cases you may find that the final HTML generated for typical page by your publish instance includes a relatively large number of <script>
elements.
In such cases, it can be useful to combine all the required client library code in to a single file so that the number of back and forth requests on page load is reduced. To do this you can embed
the required libraries into you app-specific client library using the embed property of the cq:ClientLibraryFolder
node.
When you embed CSS files, the generated CSS code uses paths to resources that are relative to the embedding library. For example, the publicly-accessible library /etc/client/libraries/myclientlibs/publicmain
embeds the /apps/myapp/clientlib
client library:
The main.css
file contains the following style:
body {
padding: 0;
margin: 0;
background: url(images/bg-full.jpg) no-repeat center top;
width: 100%;
}
The CSS file that the publicmain
node generates contains the following style, using the URL of the original image:
body {
padding: 0;
margin: 0;
background: url(../../../apps/myapp/clientlib/styles/images/bg-full.jpg) no-repeat center top;
width: 100%;
}
To trace the origin of embedded code, or to ensure that embedded client libraries are producing the expected results, you can see the names of the files that are being embedded at runtime. To see the file names, append the debugClientLibs=true
parameter to the URL of your web page. The library that is generated contains @import
statements instead of the embedded code.
In the example in the previous Embedding Code From Other Libraries section, the /etc/client/libraries/myclientlibs/publicmain
client library folder embeds the /apps/myapp/clientlib
client library folder. Appending the parameter to the web page produces the following link in the web page’s source code:
<link rel="stylesheet" href="/etc/clientlibs/mycientlibs/publicmain.css">
Opening the publicmain.css
file reveals the following code:
@import url("/apps/myapp/clientlib/styles/main.css");
?debugClientLibs=true
AEM allows for pluggable preprocessors and ships with support for YUI Compressor for CSS and JavaScript and Google Closure Compiler (GCC) for JavaScript with YUI set as AEM’s default preprocessor.
The pluggable preprocessors allow for flexible usage including:
By default, AEM uses the YUI Compressor. See the YUI Compressor GitHub documentation for a list of known issues. Switching to GCC compressor for particular clientlibs may solve some issues observed when using YUI.
Do not place a minified library in a client library. Instead provide the raw library and if minification is required, use the options of the preprocessors.
You can choose to configure the preprocessors configuration per clientlibrary or system-wide.
cssProcessor
and jsProcessor
on the clientlibrary nodeA preprocessor configuration on the clientlib node takes precedence over the OSGI configuration.
config:= mode ":" processorName options*;
mode:= "default" | "min";
processorName := "none" | <name>;
options := ";" option;
option := name "=" value;
cssProcessor: ["default:none", "min:yui"]
jsProcessor: ["default:none", "min:gcc;compilationLevel=advanced"]
jsProcessor: [
"default:typescript",
"min:typescript",
"min:gcc;obfuscate=true"
]
failOnWarning (defaults to "false")
languageIn (defaults to "ECMASCRIPT5")
languageOut (defaults to "ECMASCRIPT5")
compilationLevel (defaults to "simple") (can be "whitespace", "simple", "advanced")
For further details on GCC options, see the GCC documentation.
YUI is set as the default minifier in AEM. To change this to GCC, follow these steps.
http://<host>:<portY/system/console/configMgr
)min:gcc
.
min:gcc;obfuscate=true
.