Asset Laravel Package

Product Decisions This Supports

• Build vs. buy on asset orchestration. Every Laravel product eventually answers the same question: which CSS and JS load on this page, in what order, and with what cache-busting key. Orchestra\Asset answers it with named containers, dependency-aware ordering, versioned URLs, and Blade rendering helpers. The decision this informs is whether the team owns that container/ordering/versioning layer indefinitely or takes a package — and because the package is small enough to replicate (a few hundred lines), it makes both sides of the argument honest rather than rhetorical.
• Modular / plugin architecture as a roadmap enabler. The named-container model exists specifically for code that ships its own assets — modules, plugins, tenant themes, white-label skins. If a roadmap epic is gated on "third parties can't safely inject front-end assets into the host page without editing our layout," this is a candidate unlock rather than a rewrite. The layout renders Asset::container('head')->styles() once; each module registers from its own boot(). That indirection is the product.
• Theming and white-label go-to-market. Per-theme container registration plus versioned URLs means a theme swap or per-tenant release doesn't require reworking the base layout. That's a sales-enablement capability (white-label, enterprise branding) rather than an engineering nicety, and it's the kind of thing that's cheap to build in now and expensive to retrofit after three customers have hand-patched layouts.
• Vite migration sequencing. This is not a Vite replacement and shouldn't be scoped as one. The healthy product split is: @vite() renders compiled, hashed, tree-shaken app bundles; Orchestra Asset renders the runtime tail — vendor/CDN scripts with hard ordering constraints, per-tenant theme bundles, marketing tags, legacy pages that haven't migrated. That lets a Vite migration ship page-by-page instead of as a big-bang cutover. A PM decision to adopt this is really a decision to decouple two migrations.
• Tech-debt triage on hard-coded asset tags. If a codebase has <script> tags scattered across Blade partials with implicit ordering assumptions, this package is a mechanical path to a two-render-point discipline (styles in <head>, scripts before </body>). That's a measurable reduction in "why did checkout break" incidents, and it's a much smaller scope than a full front-end refactor.
• Multi-tenant / Octane readiness as a gating question. v6.1.0's entire documented change is "Added Laravel Octane support" — one line. If Octane or multi-tenancy is on the roadmap, the PM should treat this as an unproven claim requiring a soak test, not a shipped feature. The worst-case failure mode is tenant A seeing tenant B's theme CSS; that's a cross-tenant data leak, and it belongs in the risk register, not the changelog.

When to Consider This Package

Adopt when most of these hold:

• The app is Laravel, on a version matching the package's Laravel-major-tracked release line (v6.x ↔ a Laravel major), and the team accepts that framework upgrades become coordinated package upgrades.
• There are multiple asset contributors — modules, packages, tenants, or white-label skins — that need to inject into a host layout they don't control. This is the strongest fit; with a single contributor, the container indirection buys little.
• Dependency ordering across a small, coarse set of scripts is a real requirement (jQuery → plugin → app tail). This is the feature that is genuinely annoying to hand-roll well, and it's the single best reason to buy rather than build.
• The team already expects a Vite (or similar) bundler for compiled assets and only needs a runtime-tail renderer.
• You can absorb the maintenance risk: zero dependents, single maintainer, sparse docs (a changelog line and one description). Mitigate by vendoring or forking the small container/ordering core behind the same facade, and decide that before rollout — not after an abandonment event.

Look elsewhere when:

• The requirement is "ship less JavaScript." This package does no transpilation, tree-shaking, CSS pre-processing, or code splitting. Adopting it for that makes the build story worse, not better.
• A Content-Security-Policy with nonces, or SRI integrity= attributes on third-party scripts, is a hard requirement. The rendered output is plain <link>/<script> strings; you'd need to post-process or extend the render path. Validate this in staging with production headers enforced — a Report-Only violation won't surface until it's a broken page.
• The team wants a package with an ecosystem. Zero dependents means you are the first to hit your own edge case, and there is no community answer waiting for you.
• The scope is a single-page, single-bundle app. Vite alone is sufficient; adding a container layer is ceremony.
• Anyone on the team is uncomfortable with a fail-open system. Misspelled asset or container names produce no tag and no exception — just missing CSS on one page that looks like a browser cache bug. That's a support-ticket generator unless you commit to the debugging discipline (log resolved container contents in non-production, dump(Asset::container(...)->all()) when a tag goes missing).

Non-negotiable conditions if you do adopt:

• Publication runs as a deploy step (php artisan vendor:publish --tag=asset --force --no-interaction immediately after composer install), never at runtime from a controller or route — that's a write to the public directory under your process user.
• Version keys are deploy-correlated (git SHA or release tag), never wall-clock time, so CDN caches behave and identical builds produce identical URLs. Accept that container-level versioning is coarse — a release invalidates everything. Per-file hashing is Vite's job; don't try to out-clever the package here.
• Asset names are namespaced per module (billing.app, reports.app, never bare app); container names may be shared, asset names must not be. Silent overwrite is the collision failure mode.
• Registration lives in service providers, controllers, or view composers — never in Blade. Blade renders containers; Blade never populates them.
• Under Octane or multi-tenancy, registration happens per-request (middleware or RequestReceived listener) with an explicit flush, plus a soak test hitting the same worker twice with different tenant context and diffing the rendered <head>.

How to Pitch It (Stakeholders)

To executives: This is a small, cheap dependency that unblocks a strategic capability — modules, plugins, and white-label tenants can ship their own CSS and JS into the product without us editing layouts for each one. It also lets us sequence the Vite migration page-by-page instead of as a risky big-bang cutover, because it handles the "runtime tail" (vendor scripts with hard ordering constraints, per-tenant themes, marketing tags) that the bundler doesn't want. The cost is genuinely small: a few hundred lines of container and ordering logic, framework-native API, minimal configuration. The honest caveat is supply-chain: the package has zero dependents and a single maintainer, so we should vendor or fork the core behind the same interface as a ~1-day insurance policy before rollout — at that size it's a composer.json edit to exit, not a rewrite. Net recommendation: adopt for the modular/theming use case, do not adopt as a bundler, and treat the Octane support claim as unproven until we soak-test it.

To engineering: The value proposition is narrow and real. You get named containers, coarse dependency ordering, versioned URLs, and Blade helpers — the parts of asset management that are tedious to write and easy to write badly. You do not get a build pipeline, CSP nonce support, or SRI attributes, and you should not ask it for those. The disciplines that make it safe: render from exactly two places (head for styles, end-of-body for scripts) and never inline mid-body; register in providers/controllers/composers and never in Blade; namespace asset names per module to avoid silent overwrites; put vendor:publish --tag=asset --force in the release script next to composer install; version containers from the git SHA, not the clock. It fails open — a typo yields a missing tag and no exception — so wire up a non-production listener that logs each container's resolved contents, and use assertSeeInOrder(['jquery.js','widget.js']) as the regression test for every ordering constraint you declare. Keep declarations coarse: ['jquery'] on each plugin is fine; a 30-node DAG is where ordering bugs live. If you need Octane, read the service provider for singleton container state first and confirm the flush hook exists — then soak-test with low max_requests so workers recycle. Finally, budget an afternoon to vendor the container/ordering core: we're the only users of this thing, so on-call for it is us either way, and a local copy makes the upgrade-or-abandon decision ours rather than the maintainer's.