Big Mugs Hero Header

This project contains the PixiJS-powered hero header that we mount onto the Big Mugs WordPress site. The codebase is a standard Vite + Solid project that outputs an embeddable bundle under dist/. The intent is to ship this bundle as an npm package and load it on the WordPress site via a public CDN.

Local development

npm install
npm run dev

Open http://localhost:5173 to iterate on the header in isolation. Update the assets under src/ as needed, and keep the public API of your entry file stable so that the bundle can be mounted in WordPress without code changes.

Preparing the package for npm

1. Update package metadata
   • Choose an npm-safe name (for example, @big-mugs/hero-header).
   • Remove the "private": true flag in package.json.
   • Set an appropriate version, description, author, license, and repository field.
   • Point main, module, and types (if you ship definitions) to the built files under dist/.
   • Add an exports map if you want to control what consumers can import.
2. Verify the entry point
   • The dist/ output should expose a function that mounts the header into a DOM element.
   • Confirm any CSS or assets referenced in the bundle are included.
3. Build the package
   • Run npm run build to produce the production bundle in dist/.
   • Optionally, inspect the output and test it locally by loading index.html and manually invoking the exported function.
4. Authenticate with npm
   • Run npm login (or npm login --registry https://registry.npmjs.org if you use a different default registry).
   • Ensure you have publish rights to the chosen scope.
5. Publish
   • Bump the version number following semantic versioning (npm version patch|minor|major).
   • Run npm publish --access public to push the build to npm.
   • Tag the release in git once the publish succeeds.

Consuming the package from a CDN

After publishing, the bundle can be served from an npm CDN such as jsDelivr or unpkg. Below is an example using jsDelivr:

<script type="module">
  import mountHeroHeader from "https://cdn.jsdelivr.net/npm/@big-mugs/[email protected]/dist/index.js";

  document.addEventListener("DOMContentLoaded", () => {
    const target = document.getElementById("big-mugs-hero-root");
    mountHeroHeader(target, { /* custom options */ });
  });
</script>

Update the URL with the published package name and version. You can omit the version (@latest) while testing, but pinning a version is recommended for production stability.

Loading the header in WordPress

1. Register a container element in your theme or block markup, e.g. <div id="big-mugs-hero-root"></div>.

2. Enqueue the CDN script in WordPress:

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

   Use wp_add_inline_script if you need to pass configuration before mounting.

3. Invoke the mount function either inline (via wp_add_inline_script) or inside your theme JavaScript bundle after the CDN module loads.

Ensure cache busting by updating the version in the CDN URL whenever you publish a new release. Consider setting up automated integration tests to confirm the WordPress page loads the header correctly after each publish.