The packer
This page is for designers who want to understand what happens to their CSS and JavaScript between the design folder
and the browser. The packer is part of the ezjscore extension (extension/ezjscore/classes/ezjscpacker.php).
Warning
.htaccess slows down every request. When .htaccess files are enabled (AllowOverride anything but None), let alone
used, Apache looks for them and reads and evaluates them on every request, in every directory of the path, and
page loading times go up drastically (measured). The only real fix is to switch the feature off for
the virtual host: AllowOverride None in the HTTPS virtual host, and the rules in the virtual host's own
configuration as mod_rewrite rules. That is far faster in production speed tests and well worth the time it takes
to optimize a production configuration. Switch over right away: copy the rules of the
example HTTPS virtual host into your virtual host (with the static cache, also
staticcache_offload.conf), set AllowOverride None, run apachectl configtest, reload Apache and
test the site. The same rules for other servers: nginx, LiteSpeed,
Caddy, IIS, Velocity (built in); where virtual host rules go in a control
panel: Plesk, cPanel, DirectAdmin, ISPConfig.
On LiteSpeed or OpenLiteSpeed, the server's own page cache can also answer anonymous visitors and crawlers without PHP: Page caching with LiteSpeed and OpenLiteSpeed.
Contents
- What it does
- Where packed files live
- How a packed file is named
- Settings
- Developing with the packer off
- Troubleshooting
What it does
For each ezcss_load, ezscript_load (and the other packer operators) call, the packer:
- finds every file through the design cascade;
- at pack level 1 or more, concatenates them into one file, in the order given;
- at level 2, runs the optimizers of
ezjscore.ini [eZJSCore](JavaScriptOptimizer[]=ezjscJavascriptOptimizer,CssOptimizer[]=ezjscCssOptimizer), which remove comments and whitespace; - for CSS, rewrites relative
url()paths into absolute ones, so images and fonts referenced by your stylesheet still load from the packed location; - writes the result once and prints a single
<link>or<script>tag pointing to it.
Fewer files mean fewer requests: the media design's pagelayout/head/style.tpl names fifteen stylesheets in one
ezcss_load call, and the browser fetches one file.
Where packed files live
In the public cache of the site: var/<site>/cache/public/stylesheets/ and .../javascript/. The shipped rewrite rules
serve var/<site>/cache/public/ directly (.htaccess_root), so packed files never go through PHP once written.
How a packed file is named
With ezjscore.ini [Packer] AppendLastModifiedTime=enabled (the default in this release) a packed file is named
<md5 of the source file list and pack level>_<newest modification time of the sources>_<media>.cssfor example 82b3f6472765825fde39b69dc69ebd0a_1792109816_all.css. Consequences:
- Change a source file and its time changes, so the packed file gets a new name and browsers fetch it; no manual version query is needed (No version queries on asset links).
- Packed files can be cached by browsers for a long time.
- Old packed files stay on disk until the
ezjscore-packercache is cleared.
Settings
| Setting | Default | Effect |
|---|---|---|
site.ini [TemplateSettings] DevelopmentMode | disabled | enabled forces pack level 0 (every file on its own), unless ezjscore.ini [eZJSCore] Packer is set |
ezjscore.ini [eZJSCore] Packer | not set | disabled = level 0 always; a number 0 to 3 = that level always; enabled = the level of each call even in development mode |
ezjscore.ini [Packer] AppendLastModifiedTime | enabled | the time in the file name, as above |
ezjscore.ini [Packer] CustomHosts[] | empty | serve packed .js or .css from another host, e.g. CustomHosts[.js]=https://static.example.com |
ezjscore.ini [eZJSCore] LoadFromCDN | disabled | ezjsc::jquery from the local copy (enabled: from the CDN URLs of ExternalScripts[]) |
Change them in your design extension's or siteaccess's ezjscore.ini.append.php, never in extension/ezjscore/settings/.
Developing with the packer off
On a development or preview siteaccess:
# settings/siteaccess/<preview>/site.ini.append.php
[TemplateSettings]
DevelopmentMode=enabledEach stylesheet is then linked on its own, under its own name, so the browser's style inspector shows which file and line
a rule comes from. Never enable DevelopmentMode on a live site: it also makes the template engine check file times
on every request.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| A file is missing from the packed CSS | not found in the cascade: the debug output has "Could not find: ..."; check the path relative to stylesheets/ |
| Images in CSS broken after packing | an absolute url(/...) that points to the wrong place; use paths relative to the stylesheet |
| Admin without styles after a cache clear | the admin's head names packed files inside a template-block; clear ezjscore-packer and template-block together (exp:velocity deploy --packer) |
| One script error breaks every script | in a packed bundle all files share one file; fix the error or split the bundle |
Related pages
- Loading stylesheets
- The packer cache and deploys
- The ezcss and ezscript operators
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.