JavaScript Optimization Overview

This guide reflects the JavaScript optimizations implemented in JavaScript.php. Features are controlled by configuration keys in SysConfig::$config and run inside the main HTML optimization pipeline.

JavaScript Minification

When js_minify is enabled, ZiziCache minifies local scripts with MatthiasMullieMinifyJS and serves cached copies from wp-content/cache/zizi-cache/.

• Skips already minified files (.min.js) and adds a cache‑busting ver parameter.
• Creates a hash‑based filename and a .gz version for compatibility.
• Uses the minified file only if savings exceed 2 KB or 10%.
• Files that fail minification fall back to the original URL.

Exclude scripts via the zizi_cache_exclude_from_minify:js filter.

Defer (External & Inline)

When js_defer is enabled, ZiziCache adds defer to external scripts and can convert inline scripts into deferred data‑URI scripts.

• External scripts: removes async and adds defer.
• Inline scripts: converted to data:text/javascript and loaded with defer.
• Non‑standard script types are skipped.
• Exclusions: js_defer_excludes and the zizi_cache_exclude_from_defer:js filter.

Module Scripts

If js_defer is enabled, module scripts (type="module") are moved to the end of the document to improve rendering order.

Basic Script Delay

When js_delay is enabled, ZiziCache delays selected scripts by moving src to data-src. The core library (core.min.js) is injected automatically to handle delayed loading.

• js_delay_method: selected or all.
• js_delay_selected: keywords to delay in selected mode.
• js_delay_all_excludes: keywords to keep immediate in all mode.
• js_delay_excludes: global exclusions.

Conflict: Basic delay is skipped if js_user_interaction_delay is enabled (only one delay system can run).

Advanced User‑Interaction Delay

When js_user_interaction_delay is enabled, ZiziCache rewrites scripts into delayed placeholders and injects a handler script:

• Methods: smart, selected, all.
• Critical excludes include jquery, wp-includes, wp-admin, and core.min.js.
• Inline scripts are base64‑encoded into data-zizi-delay-inline (size limited by js_user_interaction_inline_limit).
• External scripts are converted to data-zizi-delay-src.
• Handler injection uses js_user_interaction_timeout (1-10s clamp).

Lazy Rendering (Below‑the‑Fold Content)

When js_lazy_render is enabled, ZiziCache defers rendering of heavy sections:

• Methods: hybrid (default), css, javascript.
• Auto‑detects common WordPress elements (comments, sidebars, galleries, embeds, WooCommerce sections, etc.).
• Custom selectors can be provided via js_lazy_render_selectors.
• Manual markup can use the .lazy-render class.

The enhanced lazy render library (lazyrender-enhanced.min.js or lazyrender.min.js) is injected into the page along with a configuration script (js_lazy_render_root_margin, js_lazy_render_height_cache).

jQuery Preload

When js_preload_jquery is enabled, ZiziCache inserts for jQuery (and optionally jQuery Migrate with js_preload_jquery_migrate). jQuery remains synchronous; only the download is preloaded.

Self‑Hosting External JavaScript

When self_host_third_party_css_js is enabled, external scripts are downloaded (if allowed) and served from wp-content/cache/zizi-cache/3rd-css-js/. The original URL is preserved in data-origin-src, and integrity/crossorigin attributes are removed.

Preload Library

If js_preload_links is enabled, ZiziCache enqueues assets/js/preload.min.js for visitors (not logged‑in users) to enable resource hint behavior.

Troubleshooting

• Broken scripts: add keywords to js_defer_excludes or delay exclusions.
• Conflicting delay modes: ensure only one of js_delay or js_user_interaction_delay is enabled.
• Lazy render layout issues: enable height caching or adjust root margin.