Assets Laravel Package

Getting Started

This package is the asset layer of Pollora, extracted so it runs without Laravel — the target is a classic WordPress theme, a plugin, or a Bedrock site that builds with Vite. If you're coming from Laravel, the API will look familiar; what's missing is the framework's bindings, which is exactly what the package supplies in native form.

1. composer require pollora/asset.

2. Configure your Vite build with @pollora/vite-config and set layout: 'standalone'. This is not optional — the resolver expects the manifest shape that layout produces.

3. Declare at least one container, early (theme functions.php or the plugin's main file):

   Asset::addContainer('theme', [
       // build directory / manifest location for this container
   ]);
   

4. Enqueue an entry point:

   Asset::add('app')
       ->container('theme')
       ->useVite()
       ->toFrontend();
   

Where to look first:

• AssetManager — the registry of containers; understand this before anything else.
• AssetContainer — how a build directory is described and resolved.
• AssetEnqueuer — where toFrontend() actually turns into wp_enqueue_* calls. This is where you debug "nothing appeared in the page".
• NativeViteManager — the manifest/hot reader. Read it once; it answers most "why is it loading the wrong URL" questions.
• The three contracts (ViteManagerFactory, RuntimeContext, PublicPath) — only needed when you step outside WordPress or want to swap resolution.

First real use case: a classic theme with one Vite build, one container, one toFrontend() call in functions.php. Get that working end-to-end (dev and prod) before adding a second container.

Implementation Patterns

One container per build, declared once. Theme, plugin, mu-plugin, and any separate editor build should each be their own container. Declare them in the bootstrap file that owns the build — not lazily inside an enqueue callback, or you'll race the hook.

Dev vs. production is automatic. NativeViteManager reads the hot file when present and the manifest otherwise, returning the same answers as the framework's resolver for the same files. You write one Asset::add(...) chain and it works in both modes. Treat this as the primary workflow: run npm run dev, refresh, and confirm HMR before you touch production behaviour.

Group enqueues by surface. The chain terminates in toFrontend(); keep separate Asset::add() chains per entry point rather than concatenating, so a broken build in one bundle doesn't take down the others.

Bedrock. Public paths differ from a classic install, which is why PublicPath is a contract. The framework implements it; in a native Bedrock setup make sure the path your container resolves to matches web/app/themes/... rather than the repo root. Same for the manifest URL that ends up in the page.

Plugins. Declare the container in the plugin's main file, then enqueue on the normal WordPress hook. Guard the enqueue behind a manifest-exists check so an unbuilt plugin degrades to "no assets" instead of a fatal.

Inside Laravel, keep the same API. The framework's implementations of ViteManagerFactory, RuntimeContext, and PublicPath mean Asset::add()->container()->useVite()->toFrontend() is identical on both sides. Write your theme/plugin asset code once and let the binding differ — that's the main payoff of the split.

Swapping the resolver. If you want a different manifest strategy (custom CDN, S3, a non-standard build tool), implement ViteManagerFactory and bind your own manager. Everything above it — containers, enqueuers, AssetFile — stays untouched.

Gotchas and Tips

• A stray hot file in a production deploy will serve dev-server URLs and every asset will 404. Delete it in CI, or at minimum fail the deploy if it exists. This is the single most common way this package "breaks" in production.
• Version pinning matters. This is 0.1.0. Class names are stated as unchanged from the framework, but there's no BC promise yet. Pin the constraint and read the changelog on every bump.
• The missing-build notice is your friend. The package ships a record and notice for an absent build — surface it rather than swallowing it. A silent Asset::add() that enqueues nothing is much harder to debug than a notice.
• useVite() is what selects the resolver. Omit it and you get the non-Vite path (or nothing). If assets enqueue with the wrong URLs, check the chain before you check the manifest.
• Manifest path mismatch fails quietly. The container's build directory and the PublicPath implementation must agree. Symptom: URLs that look plausible but 404, plus the missing-build notice.
• Dev server reachability is a browser concern, not a PHP one. The host recorded in hot is what the browser will request. Docker, Valet, or a remote dev box usually needs that host corrected — the resolver is doing exactly what it was told.
• Ordering. Containers must exist before the enqueue hook runs. Declare them at file scope in functions.php or the plugin main file; plugins_loaded or later is asking for trouble.
• Don't double-enqueue. AssetFile carries dependencies and versioning derived from the build. If you also call wp_enqueue_script by hand for the same handle, you'll fight the enqueuer over ordering and cache busting.
• Extension points worth knowing: the three contracts for runtime portability (useful for faking the environment in tests), and ViteManagerFactory for a custom resolver. Everything else is deliberately concrete — resist subclassing AssetContainer before you've tried a second container.