WP Lazy Lib

WP Lazy Lib is a generic WordPress plugin for opt-in frontend library loading and an optional Tailwind utility pack.

The core contract is simple: activating the plugin should not add frontend payload. Assets are registered, then loaded only when a page, block, shortcode, theme, or plugin explicitly requests them.

Included Assets

tailwind  Optional CSS utility pack, built without Tailwind preflight.
gsap      Core GSAP tweens and timelines.
gsap-scroll  GSAP with ScrollTrigger, ScrollToPlugin, and Observer.
gsap-text    GSAP with SplitText, TextPlugin, and ScrambleTextPlugin.
gsap-svg     GSAP with DrawSVGPlugin, MorphSVGPlugin, and MotionPathPlugin.
gsap-ui      GSAP with Draggable, InertiaPlugin, and Flip.
pixi      Lazy JavaScript library loaded through window.wpLazyLib.
three     Core Three.js.
three-controls  Three.js with OrbitControls.
three-gltf      Three.js with GLTFLoader.
three-draco     Three.js with GLTFLoader, DRACOLoader, and local DRACO decoder path.
phaser    Lazy JavaScript library loaded through window.wpLazyLib.
code-viewer  Prism-powered static code blocks with title, language badge, and copy button.
code-playground  Textarea-based HTML/CSS/JS playground with sandboxed iframe preview.

Tailwind is CSS. Tailwind-only requests do not enqueue the JavaScript loader. Lazy Code modules enqueue the JavaScript loader and their own scoped CSS.

PHP Usage

wp_lazy_lib_enqueue( 'tailwind' );
wp_lazy_lib_enqueue( 'gsap' );
wp_lazy_lib_enqueue( 'gsap-scroll' );
wp_lazy_lib_enqueue( 'gsap-text' );
wp_lazy_lib_enqueue( 'gsap-svg' );
wp_lazy_lib_enqueue( 'gsap-ui' );
wp_lazy_lib_enqueue( 'pixi' );
wp_lazy_lib_enqueue( 'three' );
wp_lazy_lib_enqueue( 'three-controls' );
wp_lazy_lib_enqueue( 'three-gltf' );
wp_lazy_lib_enqueue( 'three-draco' );
wp_lazy_lib_enqueue( 'phaser' );
wp_lazy_lib_enqueue( 'code-viewer' );
wp_lazy_lib_enqueue( 'code-playground' );

Invalid asset names return false and trigger the wp_lazy_lib_invalid_asset action.

Shortcode Usage

[wp_lazy_lib name="tailwind"]
[wp_lazy_lib name="gsap"]
[wp_lazy_lib name="gsap-scroll"]
[wp_lazy_lib name="gsap-text"]
[wp_lazy_lib name="gsap-svg"]
[wp_lazy_lib name="gsap-ui"]
[wp_lazy_lib name="pixi"]
[wp_lazy_lib name="three"]
[wp_lazy_lib name="three-controls"]
[wp_lazy_lib name="three-gltf"]
[wp_lazy_lib name="three-draco"]
[wp_lazy_lib name="phaser"]
[wp_lazy_lib name="code-viewer"]
[wp_lazy_lib name="code-playground"]

Shortcodes return no visible output. They only request the asset.

Lazy Code Viewer

Request the asset explicitly, then add one or more .wp-lazy-code blocks:

[wp_lazy_lib name="code-viewer"]

<div class="wp-lazy-code" data-lang="js" data-title="hello.js">
  <pre><code>const message = "Hello example";
console.log(message);</code></pre>
</div>

Supported MVP languages include HTML, CSS, JavaScript, JSON, Bash, PHP, Python, and Markdown. The module adds a header, language badge, copy button, and Prism token highlighting. It does not auto-load by scanning page content.

Lazy Code Playground

Request the playground asset explicitly, then add one or more .wp-lazy-code-playground blocks:

[wp_lazy_lib name="code-playground"]

<div class="wp-lazy-code-playground" data-title="Button Example">
  <textarea data-file="index.html">
<button id="btn">Click me</button>
  </textarea>

  <textarea data-file="style.css">
button {
  font-size: 2rem;
}
  </textarea>

  <textarea data-file="script.js">
document.getElementById("btn").textContent = "Ready";
  </textarea>
</div>

The MVP uses plain textareas. The preview runs inside iframe.srcdoc with sandbox="allow-scripts". Do not add allow-same-origin, popups, forms, or top navigation unless a later feature has a reviewed need.

Browser Usage

Request a JavaScript library through PHP or shortcode first, then load it in browser code:

const { gsap } = await window.wpLazyLib.load('gsap');
const { gsap, ScrollTrigger } = await window.wpLazyLib.load('gsap-scroll');
const { SplitText, TextPlugin, ScrambleTextPlugin } = await window.wpLazyLib.load('gsap-text');
const { DrawSVGPlugin, MorphSVGPlugin, MotionPathPlugin } = await window.wpLazyLib.load('gsap-svg');
const { Draggable, InertiaPlugin, Flip } = await window.wpLazyLib.load('gsap-ui');
const { PIXI } = await window.wpLazyLib.load('pixi');
const { THREE } = await window.wpLazyLib.load('three');
const { OrbitControls } = await window.wpLazyLib.load('three-controls');
const { GLTFLoader } = await window.wpLazyLib.load('three-gltf');
const { createGLTFLoaderWithDRACO } = await window.wpLazyLib.load('three-draco');
const { Phaser } = await window.wpLazyLib.load('phaser');

Repeated calls reuse the same dynamic import promise.

GSAP Bundles

Use the smallest GSAP bundle that fits the page:

gsap         Basic tweens and timelines.
gsap-scroll  Scroll reveals, pinned sections, scroll progress, scroll-to anchors.
gsap-text    Text splitting, typed/replaced text, scrambled text.
gsap-svg     SVG drawing, morphing, and motion paths.
gsap-ui      Draggable UI, inertia, and Flip layout transitions.

Each GSAP bundle is a separate lazy chunk. Do not request every bundle by default. Scroll/pin animations can affect page layout, so test them on real pages before publishing.

Three.js Bundles

Use the smallest Three.js bundle that fits the page:

three           Core scenes, cameras, materials, lights, and renderers.
three-controls  Adds OrbitControls for drag/zoom camera interaction.
three-gltf      Adds GLTFLoader for loading `.gltf` and `.glb` models.
three-draco     Adds GLTFLoader, DRACOLoader, and a local DRACO decoder path.

three-draco exposes helpers:

const { createDRACOLoader, createGLTFLoaderWithDRACO } = await window.wpLazyLib.load('three-draco');

const { gltfLoader, dracoLoader } = createGLTFLoaderWithDRACO();
const gltf = await gltfLoader.loadAsync('/path/to/model.glb');

// Dispose when the page/view is done with the loaders.
dracoLoader.dispose();

DRACO decoder files are bundled in assets/vendor/draco/gltf/ and the default decoder path is provided automatically when three-draco is requested through PHP or shortcode.

Tailwind Utility Pack

The Tailwind asset is a prebuilt utility CSS pack. It is intended for isolated blocks, reusable views, shortcodes, and small frontend sections that need utility classes without depending on a theme build.

The pack intentionally does not include Tailwind preflight/base reset. This keeps it safer for existing WordPress themes and ad/layout systems.

The CSS is generated from explicit Tailwind 4 @source inline() safelists in assets/src/css/tailwind.css. It does not scan theme files, project views, or project-specific pattern files.

Keep this pack generic and stable across sites. Add broad reusable utility coverage here, but put repeated or project-specific styling in theme/project CSS. Browser-delivered CSS cannot use Tailwind @apply unless that CSS goes through its own Tailwind build step.

Files under patterns/tailwind/ are examples/test fixtures only. They are not part of the production Tailwind generation workflow.

Build

Requirements:

Node.js ^20.19.0 or >=22.12.0
npm

Install and build:

npm install
npm run build
npm run test:tailwind
npm run test:lazy-code

The dist/ directory is committed intentionally so the plugin can be installed directly without a Node build step. Do not commit node_modules/.

Test

If PHP CLI is available:

php tests/zero-payload-harness.php

The harness checks the default no-payload contract, Tailwind-only behavior, repeated enqueue behavior, late Tailwind fallback, and invalid asset handling.

The Tailwind baseline check verifies representative selectors exist in the built dist/assets/tailwind-*.css file:

npm run test:tailwind

Optional Global Loader

By default, the JavaScript loader is not global. If a site intentionally wants the tiny browser API on every frontend page, it can opt in:

add_filter( 'wp_lazy_lib_auto_enqueue_loader', '__return_true' );

Use this only when the site has a real global need.

Licensing

WP Lazy Lib source code is MIT licensed. Bundled third-party libraries retain their own licenses. See THIRD-PARTY-NOTICES.md.