Composer Compile Plugin Laravel Package

Product Decisions This Supports

• Build vs. buy for asset tooling. Decides whether we keep hand-rolling per-package build scripts in CI or adopt a declarative convention where each Composer package declares its own compilation steps and the installer runs them. This is mostly a "buy" argument: the mechanism is generic plumbing, not a differentiator.
• Distribution model: ship source vs. ship built artifacts. If our packages contain JS, CSS, SCSS, or generated PHP/templates, this plugin makes "consumers do not need Node/npm" a viable product decision — composer install becomes the single setup command for downstream users.
• Roadmap shape: monolith vs. split packages. A plugin that compiles each package on install lowers the cost of splitting a monolith into reusable packages, because each package carries its own build contract instead of depending on the host app's pipeline. Useful input to any "should we extract this into a shared library?" discussion.
• Developer onboarding and time-to-first-run. Directly attacks the "install Composer, install Node, run npm, then run the build" funnel. Quantify this against support tickets and docs pages; it is the primary product benefit.
• Ecosystem/extension strategy. If we want third parties to ship add-ons that "just work" on install, a standard compile hook is infrastructure that makes third-party packages feasible without mandating our internal toolchain.
• Support-cost modeling. Fewer bespoke build instructions per package means fewer environment-specific failures reaching support; weigh against the new failure mode of installs that fail during a compile step.

When to Consider This Package

Adopt when most of the following hold:

• We maintain or consume multiple Composer packages that need generated artifacts (bundled JS/CSS, transpiled sources, compiled templates), and each currently repeats the same build boilerplate.
• Our primary consumer is not a front-end developer — integrators, agency partners, or ops teams who should never be asked to run npm.
• We want one install command as the documented happy path, and we accept that install time and install-time code execution increase.
• Builds are idempotent and cheap, or skippable when artifacts are already present.
• We are prepared to govern it: Composer 2's allow-plugins allowlist, pinned versions, and a documented opt-out for environments that forbid install-time scripts.

Look elsewhere when:

• We have one application and one asset pipeline (Vite, Webpack Encore, Mix). A plugin adds a second, less familiar build system for no gain.
• We need hermetic, reproducible, CI-only builds — the kind of supply chain where "install runs arbitrary code from a dependency" is a non-starter regardless of allowlist.
• Maintenance risk is unacceptable. This is a low-visibility package (13 stars) stewarded by a single upstream community (CiviCRM). It is effectively "we depend on CiviCRM's conventions and release cadence." Validate Composer 2 compatibility and recent release activity before committing.
• Artifacts can simply be committed or published as a release asset. If prebuilt dists are already your model, this is redundant.
• Toolchain is not PHP-centric — teams already standardizing on a JS workspace tool (pnpm/turbo) will find this fights their grain.

How to Pitch It (Stakeholders)

To executives: This is plumbing that makes our PHP packages self-installing. The bet is reduced onboarding friction and support load — downstream users run one command instead of installing and running a separate JavaScript toolchain. Cost is low (MIT-licensed, integration work is days not quarters) and the main risk is dependency on a small upstream project, which we can contain by treating it as optional and retaining the prebuilt-artifact fallback.

To engineering: It lets a package declare its compilation steps in composer.json, so the installer runs them — no bespoke per-package CI logic, no "see README for build steps." Trade-offs are explicit: install-time code execution (we must manage allow-plugins, pin versions, and provide an env-var escape hatch), longer installs, and a second build path alongside our existing asset pipeline. Recommend a time-boxed pilot on one extracted package, with success measured by onboarding steps removed and a drop in build-related support tickets, before wider rollout — and a documented decision point to drop it if upstream maintenance stalls.