Airdrop Laravel Package

Technical Evaluation

What it does: Airdrop is a deploy-time optimization for Laravel apps that skips frontend asset compilation (npm ci && npm run build) when the inputs that affect the build—package.json, lockfile, bundler config, resources/js, resources/css, etc.—are byte-identical to a previously recorded build. It is not a runtime dependency in the traditional sense; it is a CI/deploy-pipeline dependency.

Architecture fit: Good fit for teams running Laravel with Vite and a repeatable deploy pipeline (Forge, Envoyer, Ploi, Laravel Cloud, GitHub Actions, GitLab CI, or a containerized build). The value proposition is narrow but real: build minutes and deploy latency on deploys that touch only PHP, config, or templates. It is a poor fit for apps with no frontend build step, or apps where the build is already fast (<30–60s), because the coordination cost exceeds the savings.

Integration feasibility: Low-to-moderate. Typically one composer require, publishing a config file, and wiring one command into the deploy script plus persisting the state/manifest file between runs. The hard part is not the PHP—it is ensuring the state file survives across ephemeral CI runners and is shared correctly across concurrent deploys. That is a pipeline design problem the package cannot solve for you. As of v2.0.0 the require line itself changed (wilbergroup/airdrop), so this is no longer a zero-touch dependency.

What changed in v2.0.0 (and why it matters here):

• Namespace/package rename aaronfrancis/airdrop → wilbergroup/airdrop. Functionally a drop-in, but not a drop-in at the Composer level: composer.json, composer.lock, SBOM/composer audit output, CI cache keys derived from the lockfile, and any vendor/ path assumptions all change. Treat it as a dependency-identity change requiring a dedicated PR and deploy.
• Hash invalidation on upgrade (disclosed, benign). Trigger class names are part of the hash, so the first deploy on v2 rebuilds assets once and then resumes skipping. Good news: this partially answers a key open question—it confirms the hash input set extends beyond file contents to include class identity. It also means any future rename, extraction, or refactor of trigger classes forces a rebuild, which is a predictable-but-nonzero coupling between code structure and build behavior.
• Laravel 13 support and PHP 8.5 in the test matrix. Materially de-risks the "does this block our framework upgrade?" concern and is the strongest maintenance signal the package has produced to date.
• Transfer to the Wilber Group organization. The provenance oddity flagged previously (name said aaronfrancis, repo pointed at a fork) is now resolved by declaring the fork canonical. This is a positive, but it is a governance improvement, not a capacity improvement.

Technical risk:

• Stale-asset risk (highest, unchanged). Any input not covered by the hash (env-specific build flags, VITE_* variables baked at build time, postcss/tailwind config in unusual locations, a dependency pulled from a git URL, Node/bundler version drift) produces a false "no change" and ships stale or wrongly-configured assets. This is a silent production defect class, and v2 does not address it.
• Provenance — materially improved. The canonical repo and the package name now agree, and a major version with a changelog and comparison link was published. Downgrade this from "yellow flag" to "normal small-project risk."
• Package-identity hygiene (new). Two names now exist on Packagist for the same code. Verify the old name is marked abandoned pointing at the new one, and confirm no transitive path can install both. Duplicate installs would be an exotic but confusing failure.
• State store correctness (unchanged). If the manifest lives in an ephemeral path, the optimization silently no-ops (benign). If it lives in a shared, mutable location, a race between parallel deploys can produce a corrupt or misapplied state (not benign).
• Bus factor — modestly improved, still thin. An organization owns it now, but the contributor base and dependent count (0 at last check) are unchanged. You remain effectively your own maintainer for incident purposes.

Key questions for the maintainer / your own team:

1. Exactly which files and config keys are hashed, and can we extend the input set (env vars, Node version, .npmrc, private registry config)? Partially answered: trigger class names are included.
2. Does the hash include a package-identity/version component? If so, does that mean every future major bump forces a rebuild—and is that documented as intentional?
3. Is aaronfrancis/airdrop marked abandoned on Packagist with a pointer to wilbergroup/airdrop, and is v1.x receiving security fixes?
4. Where is the state persisted by default, and is it designed for shared/remote storage (S3, object store, CI cache) or only local disk?
5. What happens on a hash-store read failure or corruption — fail-open (rebuild) or fail-closed (skip build)? We require fail-open.
6. Is there a --force / bypass flag for hotfixes and rollbacks?
7. How does it interact with zero-downtime symlink deploys and with php artisan down/queue restarts in the same release hook?
8. What is the support matrix for Laravel 13 / PHP 8.5 relative to our current floor, and is there a CI matrix proving it?

Integration Approach

Stack fit: Laravel 10–13 (13 added in v2.0.0) with Vite, Composer 2, Node 18/20/22, PHP 8.5 covered in the upstream test matrix. Requires a deploy pipeline that (a) runs a PHP command before the build step and (b) can persist a small file between deploys. If your pipeline is a single Docker build stage, you need a cache mount or a remote cache to make it work.

Migration path (low-risk, reversible):

1. Decide v1 vs v2 first. If not yet adopted, start directly on v2 — there is no reason to onboard onto a now-legacy package name. If already on v1, schedule the rename as its own change.
2. Do the v2 rename as an isolated PR. composer remove aaronfrancis/airdrop && composer require wilbergroup/airdrop, re-publish the config file if the tag changed, and grep the deploy scripts and CI configs for the old name. Diff the lockfile to confirm nothing else moved.
3. Expect and verify exactly one rebuild. The first deploy after the rename must rebuild assets. Confirm via the decision log that the rebuild happened, then confirm the next deploy skips. If the second deploy does not skip, the state store is not persisting and you have found your real integration bug early.
4. Shadow mode. Add a step that computes and logs the decision ("would skip" / "would build") without actually skipping. Run for 2–3 weeks across all deploy types. This gives you a free measurement of hit rate before you accept any risk.
5. Quantify. Measure p50/p95 deploy duration and build minutes with and without. If the skip rate is below ~30% or savings are under a minute, stop here — the ongoing cognitive overhead is not worth it.
6. Enable on non-production first. Staging and preview environments, with the build still verified by a post-deploy smoke test that asserts the Vite manifest exists and asset URLs resolve.
7. Promote to production behind a pipeline flag so a single config change reverts to always-build.
8. Codify. Add the input set to the config file, commit it, and add a test that fails if a new build-affecting config file is added without being added to the hash inputs.

Compatibility considerations: Pin the new package name explicitly in composer.json (do not rely on a replace shim). Confirm Laravel version constraints against your app — v2 extends the ceiling to 13, which removes a likely blocker on your next framework upgrade. Confirm the artisan command signature is unchanged from v1 so deploy scripts need no edits. Confirm the command is non-interactive and returns sane exit codes for CI, does not assume a specific storage disk or APP_ENV, and that a missing Vite manifest forces a build rather than a skip.

Sequencing: Two distinct pieces of work, deliberately not bundled. (a) The v2 rename is a small dependency-hygiene change — do it on its own deploy, during a quiet window, and watch for the expected one-time rebuild. (b) The shadow-mode pilot is a pipeline improvement — do not bundle it with a framework upgrade or a Vite migration, since bundling makes it impossible to attribute a bad deploy to the right change. If you happen to be planning a Laravel 13 upgrade, note that v2's Laravel 13 support makes those two changes compatible but does not make them safe to ship together.

Operational Impact

Maintenance: The code surface is small, but the failure mode is asymmetric — it saves seconds and can cost an incident. Budget for one owner who reviews the package before each Laravel/Node major upgrade, because both change the asset-input surface. Pin the exact version, and record that the canonical name is now wilbergroup/airdrop anywhere the old name appears (runbooks, ADRs, onboarding docs, internal allowlists) — stale references will send the next on-call engineer to an unmaintained package. The v2.0.0 upgrade itself needs a two-line runbook entry: "rename performed, one forced rebuild expected on first deploy, verify second deploy skips."

Support: Expect questions of the form "why didn't my CSS change deploy?" Write a short runbook: how to read the decision log, how to force a rebuild, how to clear the state, and who to page. Add the bypass flag to the hotfix checklist so on-call never debugs this at 2 a.m. Add one more scenario now: "we renamed the package / refactored a trigger class and assets rebuilt unexpectedly" — that is expected behavior, not a regression, and support should be able to say so immediately rather than escalating.

Scaling: Scales fine technically — it is a hash comparison. It scales poorly organizationally: as repos, apps, and deploy targets multiply, each pipeline needs its own state store and its own input list. Gains are highest for apps with slow builds and frequent PHP-only deploys; negligible for monorepos where any change triggers a full rebuild anyway. Parallel/concurrent deploys to the same environment are the main scaling hazard — require per-environment state keys. If you run many apps, the v2 rename is a multiplier on toil: it is a one-line change per repo, but a one-line change times N plus a lockfile diff each, so schedule a sweep rather than discovering it repo-by-repo.

Failure modes and mitigations:

• Stale assets shipped → fail-open default, post-deploy assertion that the manifest hash matches the expected build inputs, canary deploy.
• State store unavailable → must rebuild, never skip; verify this behavior explicitly.
• Hash input drift (new config file added, Node bumped, trigger class renamed) → treat the input list as code; review it in PRs alongside build config changes. v2 confirms class names are in the hash, so include "did any trigger class move?" in the upgrade checklist.
• Concurrent deploy race → namespace state by app + environment + branch; reject deploys that cannot acquire the state lock.
• Rollback confusion → document that rollback restores previously built assets and interacts with the state file; verify a rollback rebuilds rather than trusting stale state. In particular, do not roll back across the v2 rename — the package name change is not reversible by redeploying artifacts alone.
• Package-identity drift → pin wilbergroup/airdrop, confirm the old name is marked abandoned upstream, and add a dependency-review rule so the old name cannot reappear.
• Bus factor → ownership moved from an ambiguous fork to a named organization, but the maintainer base is still thin; assume you may own it.

Ramp-up: Half a day for the engineer wiring it into the pipeline, plus roughly an hour for the v2 rename PR and its verification if already adopted. A one-hour briefing for the on-call rotation; a short ADR recording the decision, the measured savings, the input list, the bypass procedure, and the new canonical package name. The v2.0.0 release is a net-positive maintenance signal and removes the framework-upgrade blocker, but it does not change the economics: the payoff is still small and still must be measured. Recommendation: migrate to wilbergroup/airdrop v2 as routine dependency hygiene on its own deploy, expect and verify exactly one rebuild, then continue the standing plan — pilot in shadow mode, adopt only if skip rate and savings clear a pre-agreed threshold, and treat production enablement as a reversible, flag-gated change.