8.2 Debugging Client-Side Libraries & Granite Dumplibs

8.2 Debugging Client-Side Libraries & Granite Dumplibs

Core Principle: Client-Side Libraries (clientlibs) manage the delivery of CSS and JavaScript in AEM Sites applications. While clientlibs offer concatenation, minification, dependency management, and URL fingerprinting, debugging them can be challenging when scripts fail to execute, styles collide, or minification aborts silently. Mastering diagnostic tools like Granite Dumplibs (/libs/granite/ui/content/dumplibs.html) and the ?debugClientLibs=true query parameter is essential for rapid troubleshooting.

---

1. Clientlib Architecture & Compilation Lifecycle

An AEM client library is a repository node of type cq:ClientLibraryFolder. The Granite HTML Client Library Manager processes clientlib nodes into optimized CSS and JavaScript bundles through an automated compilation lifecycle:

+-------------------------------------------------------------------------+
|          cq:ClientLibraryFolder (/apps/wknd/clientlibs/clientlib-site)  |
|  - categories: ["wknd.site"]                                            |
|  - dependencies: ["core.wcm.components.commons"]                       |
|  - embed: ["wknd.grid"]                                                 |
|  - allowProxy: true                                                     |
+-------------------------------------------------------------------------+
                                     |
                                     v
+-------------------------------------------------------------------------+
|                      Granite HTML Client Library Manager                |
|  1. Parse js.txt and css.txt index files                                |
|  2. Resolve recursive dependency graph                                  |
|  3. Inline embedded libraries (embed)                                   |
|  4. Run CSS/JS Processors (GCC / YUI Minification & Preprocessors)      |
|  5. Cache compiled payloads under /var/clientlibs                       |
+-------------------------------------------------------------------------+
                                     |
                                     v
+-------------------------------------------------------------------------+
|                        Proxy Delivery Layer                             |
|  /etc.clientlibs/wknd/clientlibs/clientlib-site.lc-1a2b3c-lc.min.js     |
+-------------------------------------------------------------------------+

Critical Node Properties

---

2. Granite Dumplibs Diagnostic Console (/libs/granite/ui/content/dumplibs.html)

The Granite Dumplibs console is AEM's built-in administrative suite for inspecting, validating, and debugging the runtime state of all registered client libraries. Located at:

$\mathbf{/libs/granite/ui/content/dumplibs.html}$

Primary Console Tabs & Diagnostic Tools

+-----------------------------------------------------------------------+
|                         Granite Dumplibs Console                      |
+-----------------------------------------------------------------------+
| [By Category] | [By Path] | [Dependencies] | [Test Output] | [Rebuild]|
+-----------------------------------------------------------------------+

1. By Category View

• Displays an alphabetical index of all clientlib categories currently registered in the OSGi clientlib service registry.
• Diagnostic Capability: Search for any category (e.g. wknd.site). The tool reveals every cq:ClientLibraryFolder path registered under that category, exposing accidental category collisions where multiple third-party or legacy packages register duplicate categories.

2. By Path View

• Lists all physical repository paths containing cq:ClientLibraryFolder nodes under /apps, /libs, and /etc.
• Displays the primary type, category names, dependency declarations, and embed lists for each folder.

3. Dependencies Graph View

• Evaluates the complete recursive dependency tree for any specified category.
• Diagnostic Capability: Identifies cyclic dependencies (e.g. Library A depends on B, which depends on A) and highlights unresolved dependencies in red when a declared category does not exist in the repository.

4. Test Output & Print Channel View

• Allows developers to simulate HTL clientlib inclusions for both CSS and JS channels.
• Outputs the raw, concatenated, and minified stream directly into the browser, enabling developers to confirm whether a specific .js file declared in js.txt was successfully bundled into the output.

5. Rebuild Client Libraries (/libs/granite/ui/content/dumplibs.rebuild.html)

• In local development, AEM caches compiled clientlib artifacts in memory and under /var/clientlibs.
• Clicking Invalidate Caches or Rebuild Libraries purges the cached artifacts and forces the HTML Client Library Manager to re-parse all js.txt and css.txt files from JCR sources.

---

3. In-Browser Diagnostics: ?debugClientLibs=true

In standard production and staging environments, AEM concatenates all source files into a single bundle and applies minification. When a JavaScript runtime exception occurs (e.g. TypeError: Cannot read properties of undefined), the browser's Developer Tools stack trace points to a minified bundle line (e.g. clientlib-site.min.js:1:48201), making root-cause analysis nearly impossible.

The Debug Parameter

Appending ?debugClientLibs=true to any page URL completely alters the Client Library Manager's output:

$\text{https://wknd.site/us/en/adventure.html}\mathbf{?debugClientLibs=true}$

Operational Effects of ?debugClientLibs=true:

1. Exposes source composition: Generated debug output identifies or references the underlying source files instead of hiding them behind only the optimized production payload.
2. Avoids the normal minified view: This makes original source and generated imports easier to inspect.
3. Reveals origin paths: Use page source, the generated library, and browser developer tools to trace files back to their clientlib location:

<!-- Start Client Library: /apps/wknd/clientlibs/clientlib-site/js/navigation.js -->
<script type="text/javascript" src="/etc.clientlibs/wknd/clientlibs/clientlib-site/js/navigation.js"></script>
<!-- End Client Library: /apps/wknd/clientlibs/clientlib-site/js/navigation.js -->

<!-- Start Client Library: /apps/wknd/clientlibs/clientlib-site/js/carousel.js -->
<script type="text/javascript" src="/etc.clientlibs/wknd/clientlibs/clientlib-site/js/carousel.js"></script>
<!-- End Client Library: /apps/wknd/clientlibs/clientlib-site/js/carousel.js -->

Developer Workflow in Browser DevTools

• Open the browser Console tab: Stack traces now reference the exact source file and line number (e.g. navigation.js:42).
• Open the Sources / Debugger tab: Set breakpoints, inspect local variables, and step through functions directly without generating client-side source maps.
• Inspect the Network waterfall: Determine whether a specific individual script is experiencing 404 Not Found errors or high download latency.

---

4. Common Clientlib Pathologies & Remediation

1. Load Order Problems: dependencies vs. embed

A frequent architectural flaw in AEM Sites is the misuse of embed when dependencies is required.

+-----------------------------------+     +-----------------------------------+
|          dependencies             |     |              embed                |
+-----------------------------------+     +-----------------------------------+
| - Loaded as SEPARATE HTTP tags    |     | - Inlined DIRECTLY into bundle    |
| - Guarantees execution ORDER      |     | - Single combined HTTP payload    |
| - Shared across multiple libs     |     | - Duplicates code if re-embedded  |
| - Best for: jQuery, Core Commons  |     | - Best for: Micro-plugins, icons  |
+-----------------------------------+     +-----------------------------------+

[!WARNING] The Embed Duplication Hazard: If clientlib-header embeds jquery and clientlib-footer also embeds jquery, jQuery is downloaded and executed twice. The second execution overwrites the global window.$ object, destroying all event listeners registered by plugins initialized during the first execution!

Remediation Rule: Always use dependencies for shared foundational libraries, framework runtimes, and Core Component clientlibs. Restrict embed to private sub-modules that belong strictly to that specific clientlib.

2. Missing Category Dependencies & ReferenceError

When an AEM page loads, the browser console reports: Uncaught ReferenceError: $ is not defined or Uncaught ReferenceError: Granite is not defined.

Root Cause Analysis:

• The site clientlib executes code calling $(document).ready(...), but the category core.wcm.components.commons.site.jquery was neither declared in the clientlib's dependencies property nor included in the page's HTML <head>.
• Inspect the page template structure under /conf/wknd/settings/wcm/templates/.../structure or customheaderlibs.html. Verify that dependency clientlibs are loaded before component clientlibs.

3. Minification Engine Errors (GCC / YUI)

A developer adds modern ECMAScript features (e.g. optional chaining item?.name, nullish coalescing val ?? defaultVal, or ES6 arrow functions) to a clientlib file. In the browser, the script fails to execute, or the clientlib file returns HTTP 500.

Inspecting error.log:

*ERROR* [0:0:0:0:0:0:0:1 [1695478900123] GET /etc.clientlibs/wknd/clientlib-site.min.js HTTP/1.1]
com.adobe.granite.ui.clientlibs.impl.HtmlLibraryManagerImpl Error during minification of
/apps/wknd/clientlibs/clientlib-site/js/checkout.js
com.google.javascript.jscomp.RhinoError: Parse error. syntax error at /apps/wknd/.../checkout.js line 15

Root Cause: AEM's built-in minifier (Google Closure Compiler or YUI) cannot parse modern ES syntax without transpilation. Remediation Options:

1. Transpile code to standard ES5/ES6 using Babel, Webpack, or Vite in the frontend build pipeline before copying to ui.apps.
2. Disable minification for that specific clientlib by setting jsProcessor=[default:none,min:none] on the cq:ClientLibraryFolder node.

4. Stale Clientlibs & Clientlib Fingerprinting

Following a production code release, end users report broken layouts or missing features until they perform a hard refresh (Cmd+Shift+R or Ctrl+F5).

Root Cause: The browser and Dispatcher cached the old clientlib-site.min.js file with an aggressive Cache-Control: max-age=31536000 header. Dispatcher was not flushed, or the browser cache held the old URL.

The Solution: Configured Long-Cache Clientlib URLs When a project enables a supported long-cache clientlib URL strategy, the public URL can contain a version token:

$\mathbf{/etc.clientlibs/wknd/clientlibs/clientlib-site.lc-1a2b3c4d5e-lc.min.js}$

• The version token changes when the configured mechanism detects a new clientlib version.
• The browser treats the new URL as a different resource.
• Cache lifetime still follows the actual CDN, Dispatcher, and response-header configuration; do not infer immutable or infinite caching from allowProxy.

---

5. Diagnostic Summary Checklist