Big Mugs Hero Header

PixiJS-powered hero header that ships as an npm package and is consumed on the Big Mugs WordPress site through a CDN.

✨ Overview

• Tech stack: PixiJS rendered inside a Vite + Solid project.
• Goal: Develop the hero header in isolation, publish it to npm, and load it on WordPress via an npm CDN (jsDelivr, unpkg, etc.).
• Output: A production-ready bundle in dist/ that auto-mounts the Pixi widget from a CDN script while exposing an opt-in JavaScript API for manual control.

🧑‍💻 Local development

npm install
npm run dev

Visit http://localhost:5173 to iterate on the header independently of WordPress. Keep the public API of the entry file stable so the published bundle can be safely updated without changing the WordPress integration code.

🏗️ Project layout

| Path | Purpose | | --- | --- | | src/ | Source files for the PixiJS scene and Solid entry point. | | public/ | Static assets copied as-is into the build. | | dist/ | Generated output after running npm run build; this is what gets published to npm/CDN. | | scripts/ | Helper scripts for build or deployment tasks. |

🚀 Publishing to npm

1. Prepare package.json
   • Select an npm-safe name (e.g. @big-mugs/hero-header).
   • Remove the "private": true flag.
   • Fill in version, description, author, license, and repository.
   • Ensure main, module, and types (if shipping TypeScript types) point to the files under dist/.
   • Optionally define an exports map to control the public surface area.
2. Verify the entry point
   • Confirm the build exports a function that mounts the header into a provided DOM node.
   • Bundle any required CSS or static assets.
3. Build the package
   • Run npm run build to emit the production bundle into dist/.
   • Test locally by opening index.html or importing the bundle into a sandbox page.
4. Authenticate & publish
   • Run npm login (ensure you have rights to the chosen scope).
   • Bump the version following semantic versioning: npm version patch|minor|major.
   • Publish with npm publish --access public.
   • Create a git tag once the publish succeeds.

☁️ Loading from an npm CDN

Example using jsDelivr (the script self-mounts anywhere it finds the widget attribute or fallback ID):

<div data-big-mugs-widget="homepage-header"></div>
<script
  src="https://cdn.jsdelivr.net/npm/@big-mugs/[email protected]/dist/big-mugs-widgets.js"
  defer
></script>

Pin the URL to the published version you want to serve. When the script executes it automatically mounts the Pixi application into any element matching [data-big-mugs-widget="homepage-header"] or #homepage-header-widget.

If you need manual control, the bundle assigns helpers to window.BigMugsWidgets.homepageHeader:

window.BigMugsWidgets.homepageHeader.mountAll();
// or mount a specific element
window.BigMugsWidgets.homepageHeader.mount(document.querySelector('#custom-container'));

Funky burger menu widget

The package also exposes a Pixi-powered burger menu button that can replace a standard mobile menu trigger. Add an element with the data-big-mugs-widget="funky-burger-menu" attribute and the CDN script will auto-mount the animated button. Manual control is available via window.BigMugsWidgets.funkyBurgerMenu:

const handle = await window.BigMugsWidgets.funkyBurgerMenu.mount(document.querySelector('#menu-toggle'));
handle.onToggle((isOpen) => {
  document.body.classList.toggle('nav-open', isOpen);
});

The widget handle exposes open(), close(), toggle(forceState?), and isOpen() helpers along with an onToggle listener for synchronising the menu state with the rest of your application.

🧩 Integrating with WordPress

1. Add the mount element where the animation should appear, e.g. <div data-big-mugs-widget="homepage-header"></div>.

2. Enqueue the CDN bundle in your theme or plugin:

   function big_mugs_enqueue_hero_header() {
       wp_enqueue_script(
           'big-mugs-hero-header',
           'https://cdn.jsdelivr.net/npm/@big-mugs/[email protected]/dist/big-mugs-widgets.js',
           [],
           null,
           true
       );
   }
   add_action( 'wp_enqueue_scripts', 'big_mugs_enqueue_hero_header' );

3. (Optional) Trigger window.BigMugsWidgets.homepageHeader.mountAll() from your script if you prefer to mount after custom logic (the auto-mount will simply no-op if it already ran).

4. Update the CDN URL version whenever you publish a new release to ensure cache busting.

🔁 Release checklist

• [ ] Update source assets and confirm the public API has not changed unexpectedly.
• [ ] Run npm run build and smoke test the generated bundle.
• [ ] Update CHANGELOG.md (if present) and bump the version.
• [ ] Publish to npm and tag the release in git.
• [ ] Update the WordPress CDN reference to the new version and verify the site in production.

Happy shipping! 🚢