Merge multiple JS/CSS files into one in Adobe AEM

Statement: How to merge multiple JS/CSS files into one
Solution:

• In this example used proxy clientlibs approach, this is avail­able and rec­om­mend­ed since AEM6.2
• The AEM Client Library (or ClientLib) func­tion­al­i­ty will man­age all your JavaScript and CSS resources in your appli­ca­tion. It takes cares of depen­den­cy man­age­ment, merg­ing files and mini­fy­ing con­tent (remov­ing unnec­es­sary white spaces).

The fol­low­ing appli­ca­tion sce­nar­ios will be explained:
mul­ti­ple com­po­nents with their own JavaScript and CSS files
CSS resources have to go in the JavaScript resources at the end of the page
Resources need to be mini­fied
chang­ing the mini­fi­ca­tion engine
Let’s get start­ed!

Step 1: Creating components and ClientLib nodes
First, we make a few com­po­nents, in this exam­ple 3 com­po­nents are used, we do this all via CRXDE-lite (http://localhost:4502/crx/de).

Next, we are going to add a “clientlib” node of type “cq: ClientLibraryFolder”, inside this node the JavaScript and CSS resources are stored.

Add a prop­er­ty to every “clientlib” node called “cat­e­gories” of type String[] with the sin­gle val­ue of “myproject.components” (to get a String[] type click the “Mul­ti” but­ton).

Now add a Boolean prop­er­ty “allow­Proxy”, and set this to true. This will make the clientlibs avail­able via the url /etc.clientlibs/, so it means they are not hav­ing the /apps ref­er­ence.

Your com­po­nents-fold­er will look now like this:

Step 2: Adding JavaScript and CSS resources
Now we are going to add some sim­ple JavaScript and CSS resources in the “clientlib” nodes.

Cre­ate fol­low­ing files inside of your “clientlib” fold­er of “MyFirst­Com­po­nent”:
first.css

.firstContainer { 

     margin-top:10px; 

}
first.js

/* 

 * This is the comment of the function 

 */ 

function getNameFirst() { 

 // return the name 

 return "some value"; 

}

js.txt

# mentions all the JavaScript resources of the ClientLib first.js

css.txt

# mentions all the CSS resources of the ClientLib first.css

And repeat the same thing for the oth­er com­po­nents to achieve some­thing that looks like this:

The con­fig­u­ra­tion of the com­po­nents are now fin­ished.

Step 3: Using ClientLibs in your component
Now the set­up of the ClientLib is fin­ished we can invoke the ClientLibs in your page com­po­nents. When you are using a JSP you can use cq:includeClientlib. In case you are using the HTML Tem­plate Lan­guage (HTL), you can use the data-sly-call to invoke the ClientLib. In this arti­cle HTL will be used for the exam­ples.
We start with putting the fol­low­ing into the ele­ment of our page:

The val­ue of the “cat­e­gories” prop­er­ties of the “clientlib” nodes are “myproject.components”, which is what we need to pro­vide above.
This results in the fol­low­ing HTML-out­put:

This has a few down­sides:
6 serv­er calls have to be made to fetch the resources.
Appli­ca­tion struc­ture is exposed.

Step 4: Merging files
To merge the sev­er­al clientlib files into one, we define a clientlibs that is embed­ding the oth­er cat­e­gories. Exam­ple here is tak­en from /app­s/w­ere­tail/­clientlib­s/­clientlib-base.

Step 5: Dependencies
Anoth­er prop­er­ty you can add to the “clientlib” node is “depen­den­cies”, this way you can define depen­den­cies between ClientLibs.
Let’s add a depen­den­cy on “cq.jquery”:

When you now reload the page the depen­den­cy is writ­ten:

Step 6: Minify and Gzip
To deliv­er a bet­ter per­for­mance you can enable “Mini­fy” and “Gzip” for the “Adobe Gran­ite HTML Library Man­ag­er” (pre­vi­ous­ly also called “Day CQ HTML Library Man­ag­er”), in the Felix Con­fig­u­ra­tion con­sole (http://localhost:4502/system/console/configMgr). These set­tings are rec­om­mend­ed for pro­duc­tion instal­la­tions.

By default, the YUI com­pres­sor is used when mini­fy­ing files, you can bet­ter use the GCC (Google Clo­jure Com­pil­er) for this.

This is described here: https://helpx.adobe.com/experience-manager/kb/how-to-change-the-minification-engine-for-client-libraries-in-AEM.html

A common error with proxy clientlibs
When you use proxy clientlibs, then you may run into this error:
“Unable to proxy yourfont.ttf. No sup­port­ed type for .ttf”, this can hap­pen for types oth­er than JS/CSS.

Rea­son for this is that resources oth­er than JS/CSS need to be put into a fold­er called resources.

Exam­ple from We.Retail: https://​github​.com/​A​d​o​b​e​-​M​a​r​k​e​t​i​n​g​-​C​l​o​u​d​/​a​e​m​-​s​a​m​p​l​e​-​w​e​-​r​e​t​a​i​l​/​t​r​e​e​/​m​a​s​t​e​r​/​u​i​.​a​p​p​s​/​s​r​c​/​m​a​i​n​/​c​o​n​t​e​n​t​/​j​c​r​_​r​o​o​t​/​a​p​p​s​/​w​e​r​e​t​a​i​l​/​c​l​i​e​n​t​l​i​b​s​/​c​l​i​e​n​t​l​i​b​-​s​ite

FAQ
Q: I don’t want to have all my JavaScript ref­er­ences in the
A: Move the data-sly-call to the right loca­tion in your tem­plate, you can use ClientLib mul­ti­ple times
Q: Where are the gen­er­at­ed files stored in AEM?
A: They are stored in /var/clientlibs
Q: When devel­op­ing I want to have sin­gle file ref­er­ences in my HTML
A: Enable the debug-option in the HTML Library Man­ag­er
Q: Is there a con­sole so I can see the depen­den­cies?
A: Yes, look at this page http://server/libs/cq/ui/content/dumplibs.html
Q: Are there debug­ging options avail­able?
A: Yes, ?debugClientLibs=true writes out sin­gle files
Q: Can I rebuild the ClientLibs?
A: Yes, via this url: /libs/granite/ui/content/dumplibs.rebuild.html
Q: How can I use cache-bust­ing and ClientLibs?
A: You can enable the hash­ing of the url via ‘ver­sioned ClientLibs’.
Q: Do you have an exam­ple of this?
A: Yes, the “core” com­po­nents can be used as a reference: https://git.corp.adobe.com/CQ/aem-core-wcm-components
Q: What is the best prac­tice with regards to per­for­mance and caching
A: Via mod_expires / mod_deflate and the use of cache-bust­ing you can cache the css/js files on the brows­er to increase over­all per­for­mance of your pages. All of this will hap­pen in com­bi­na­tion with the dis­patch­er.

How to embed multiple categories.
In AEM, a category include will merge and compress all the files into a single js (or css) include. This is done per category include.
If you want to merge multiple categories, you should consider using the embed option in categories dependencies. How this is works is:

1. Create a new category (for e.g. cq-embed)
2. Define embed dependencies ('cq.foundation-main','cq.shared') for the new category you have created.
3. Reference your new category.

Reference Article: http://blogs.adobe.com/experiencedelivers/experience-management/clientlibs-explained-example/