AEM Clientlibs: Difference between Dependencies and Embed

For quite some time, I had a hard time understanding the differnce between the ‘dependencies[]’ and ’embed[]’ properties of AEM Clientlibs. I found help by reading the documentation and other sites. I created some diagrams below to illustrate their behaviors when used in a project.

But first let’s explain what each property does:

category : This is the identifier into which categories a clientlib belongs. A clientlib can have one or more categories.

dependencies : This defines the other categories that the current clientlib depends upon. The dependencies will be included in the page along with the dependent clientlib.

This property is transitive – if Clientlib A depends on Clientlib B which depends on Clientlib C, then all clientlibs will be included in the page.

embed : This defines the categories which will be combined to the current clientlib. AEM will merge all clientlibs into the current clientlib. This is usually used for minimizing requests and for accessing clientlibs which are not supposed to be exposed to public.

Take note that the embed property is NOT transitive – If Clientlib A embeds Clientlib B which embeds Clientlib C, then only Clientlib A and B will be included in the page. Clientlib A and B will be combined into one CSS and JS files as well. In order to include Clientlib C, it must be added to the embed property of Clientlib A as well.

Another note, the order of embed is important for the CSS and JS to work properly.

For my diagrams, I have 5 clientlib categories: ‘myproject.all’, ‘myproject.site’, ‘myproject.components’, ‘myproject.bootstrap’, and ‘myproject.jquery’. Only ‘myproject.all’ will be included in the template while the rest will be either dependencies or embeds to ‘myproject.all’.

<sly data-sly-call="${clientLib.css @ categories='myproject.all'}" data-sly-unwrap/>
<sly data-sly-call="${clientLib.js @ categories='myproject.all'}" data-sly-unwrap/>

DIAGRAM 1

For Diagram 1, ‘myproject.all’ depends on ‘myproject.site’ and ‘myproject.components’. In turn, ‘myproject.site’ depends on ‘myproject.bootstrap’ which depends on ‘myproject.jquery’.

HTML Output:

<!- CSS ->
	<link rel="stylesheet" href="/apps/myproject/components/content/carousel/clientlib.css" type="text/css">
	<link rel="stylesheet" href="/etc/designs/myproject/bootstrap.css" type="text/css">
	<link rel="stylesheet" href="/etc/designs/myproject/site.css" type="text/css">
	<link rel="stylesheet" href="/etc/designs/myproject/all.css" type="text/css">

<!- JS ->
<script type="text/javascript" src="/apps/myproject/components/content/pdf-viewer.js"></script>
<script type="text/javascript" src="/apps/myproject/components/content/carousel.js"></script>
<script type="text/javascript" src="/etc/designs/myproject/jquery.js"></script>
<script type="text/javascript" src="/etc/designs/myproject/bootstrap.js"></script>
<script type="text/javascript" src="/etc/designs/myproject/site.js"></script>
<script type="text/javascript" src="/etc/designs/myproject/all.js"></script>

DIAGRAM 2

For Diagram 2, ‘myproject.all’ embeds ‘myproject.site’ and ‘myproject.components’. In turn, ‘myproject.site’ embeds ‘myproject.bootstrap’ which embeds ‘myproject.jquery’.

HTML Output:

<!- CSS ->
	<link rel="stylesheet" href="/etc/designs/myproject/all.css" type="text/css">

<!- JS ->
<script type="text/javascript" src="/etc/designs/myproject/all.js"></script>

There are now two files but only the CSS and JS files from ‘myproject.all’, ‘myproject.site’, and ‘myproject.components’ were included.

 

DIAGRAM 3

For Diagram 3, myproject.all embeds both ‘myproject.site’ and ‘myproject.components’. In turn, ‘myproject.site’ depends on ‘myproject.bootstrap’ which embeds ‘myproject.jquery’.

HTML Output:

<!- CSS ->
	<link rel="stylesheet" href="/etc/designs/myproject/bootstrap.css" type="text/css">
	<link rel="stylesheet" href="/etc/designs/myproject/all.css" type="text/css">

<!- JS ->
<script type="text/javascript" src="/etc/designs/myproject/bootstrap.js"></script>
<script type="text/javascript" src="/etc/designs/myproject/all.js"></script>

Here, all.css contains the CSS files from ‘myproject.all’, ‘myproject.site’, and ‘myproject.components’. While bootstrap.css contains the Bootstrap CSS files (jQuery has no CSS files). all.js is combined JS files from ‘myproject.all’, ‘myproject.site’ and ‘myproject.components’. While bootstrap.js contains both the Bootstrap and jQuery JS files.

 

DIAGRAM 4

For Diagram 4, ‘myproject.all’ embeds both ‘myproject.site’ and ‘myproject.components’. In turn, ‘myproject.site’ depends on ‘myproject.bootstrap’ which depends on ‘myproject.jquery’.

HTML Output:

<!- CSS ->
	<link rel="stylesheet" href="/etc/designs/myproject/bootstrap.css" type="text/css">
	<link rel="stylesheet" href="/etc/designs/myproject/all.css" type="text/css">

<!- JS ->
<script type="text/javascript" src="/etc/designs/myproject/jquery.js"></script>
<script type="text/javascript" src="/etc/designs/myproject/bootstrap.js"></script>
<script type="text/javascript" src="/etc/designs/myproject/all.js"></script>

all.css contains the CSS files from ‘myproject.all’, ‘myproject.site’, and ‘myproject.components’. While bootstrap.css contains the Bootstrap CSS files (jQuery has no CSS files).
all.js is combined JS files from ‘myproject.all’, ‘my.project.site’, and ‘myproject.components’. bootstrap.js contains both the Bootstrap JS files and jquery.js contains the jQuery JS files.

CONCLUSION

Hopefully, these diagrams helped you to understand how embed and dependencies work together for Client Libraries. It’s up to your architecture on how you will mix and match this properties for your projects.
A useful tool for tracing dependencies can be found in at http://localhost:4502/libs/cq/ui/content/dumplibs.html

I used yuml.me to create the diagrams.

SOURCES

• Using Client-Side Libraries (AEM 5.6.1)
• Using Client-Side Libraries (AEM 6.1)
• stackoverflow: What is the difference between embed[] and dependencies[] for type ClientLibraryFolder?
• Clientlibs explained by example – Feike Visser