ClientLibs deep dive
Purpose: Categories, dependencies vs embeds, proxying, minification and cache-busting — beyond the Session 7 basics.
Who this page is for
| Audience | Why it matters to you |
|---|
| Frontend engineers | Bundling reference |
Folder properties reference
| Property | Effect |
|---|
| categories | Names this lib participates in (a lib can serve several) |
| dependencies | Categories loaded before, as separate files |
| embed | Categories merged into this lib's output |
| allowProxy | Serve via /etc.clientlibs proxy (required for /apps libs on publish) |
| jsProcessor / cssProcessor | Per-lib minification config (e.g. min:gcc) |
| channels | Device-channel targeting (rare) |
dependencies vs embed decision
| Question | dependencies | embed |
|---|
| Shared vendor lib used by several bundles? | ✔ (cache once) | ✗ (duplicated bytes) |
| Component CSS into the site bundle? | ✗ (request per lib) | ✔ (one file) |
| Must load before your code executes? | ✔ ordering guaranteed | ✔ within one file |
Typical shape: phi.dependencies (vendor, rarely changes — great cache hit rate) ← dependency of phi.site (embeds all component libs — changes each release).
Serving & caching
allowProxy=true + include via category → URLs like /etc.clientlibs/phi-academy/clientlibs/clientlib-site.min.ABC123.css when versioned clientlibs (Versioned ClientLibs transformer / long cache key) are enabled — content-hash cache-busting, so dispatcher/CDN can cache forever.- Without versioning you depend on dispatcher flushes for clientlib updates — enable versioning; it removes a whole incident class.
- Debugging:
?debugClientLibs=true splits bundles; the Dumplibs tool (/libs/granite/ui/content/dumplibs.html) lists every lib, category and path.
Rules
- One include mechanism: the HTL clientlib template (
clientlib.all/css/js) — never hardcode <script src> to repo paths. - CSS in head (
clientlib.css), JS before </body> (clientlib.js) unless you have a measured reason. - Keep categories few and intentional; a category-per-component defeats bundling.