Airdrop Laravel Package

Getting Started

Airdrop is a deployment-time shortcut: it answers the question "do these assets actually need rebuilding?" so your deploy script can skip npm ci && npm run build when nothing frontend-related changed.

As of v2.0.0 the package moved to the Wilber Group organisation. The vendor name changed, the code did not — it's a drop-in replacement.

Minimal setup:

1. Install as a dev dependency (it's a build/deploy tool, not runtime):

   composer require --dev wilbergroup/airdrop
   

2. Upgrading from 1.x (hammerstone/airdrop, originally aaronfrancis/airdrop):

   composer remove hammerstone/airdrop
   composer require --dev wilbergroup/airdrop
   

   No code changes required beyond the vendor name — same config keys, same Artisan commands, same behaviour. Expect one rebuild on the first deploy after the upgrade (see Gotchas).
3. Publish the config if you want to customise which paths are watched:

   php artisan vendor:publish --tag=airdrop-config
   

4. Guard your build step in the deploy pipeline with the provided check command:

   if php artisan airdrop:check; then
       npm ci && npm run build
   fi
   

   (The exact command name is in the README — confirm the signature on install rather than hard-coding it from memory. Reference it by its Artisan name, never by vendor namespace, so package renames like this one don't touch your pipeline.)

First use case to try: a single-server or Forge/Envoyer deployment where most pushes only touch PHP. Wire the check in front of your existing build command and watch deploy times drop for backend-only commits.

Where to look first: the config/airdrop.php file (watched paths, base ref, enabled environments) and the deploy examples in the README — that's where the "should I build?" decision is actually controlled.

Implementation Patterns

Conditional build in a deploy hook. The primary pattern. Put the check in the after:deploy / pre-build step so the frontend toolchain only runs when Airdrop says it's required. Keep the fallback (npm run build) unconditional in failure paths — a skipped build that should have run is far more expensive than a redundant build.

Diff-based skip across releases. Airdrop compares the current tree against a reference (typically the previous deployed commit or a configured base ref). If no file under resources/js, resources/css, package.json, package-lock.json, or vite.config.* changed, the build is skipped. This makes it ideal for Git-driven deploys where every release has a known parent.

CI artifact reuse. Build once in a dedicated CI job, upload public/build as an artifact, and let Airdrop on the target hosts recognise that the compiled output is current and skip recompiling. This pairs well with GitHub Actions matrix or multi-server deploys where you do not want to run Vite N times.

Envoyer / Forge / Deployer integration. Airdrop slots into the standard "clone → composer install → build → activate" recipe as a single-line conditional. Keep the guard as the immediate predecessor of the build command so the diff window is accurate.

Local pre-commit or pre-push hooks. Less common, but useful on large monorepos: run the check before npm run build locally so frontend devs who only edited PHP aren't waiting on Vite.

Config-driven path lists. Extend the watched-path globs whenever you add a new frontend entrypoint (e.g. a second Vite config, Tailwind config, or an importmap.php in a Rails-style asset setup). Anything that can invalidate your built output must be in that list.

Stage the v2 upgrade deliberately. Because the upgrade forces exactly one asset rebuild, land it as its own commit on a quiet deploy, not bundled with a frontend change you actually need to measure. If you run blue/green or multi-server deploys, upgrade the fleet from a single commit so every host takes its one rebuild at the same time rather than trickling rebuilds across successive releases.

Gotchas and Tips

• The v2 rename is a Composer-level break, not a code-level one. Anything that pinned hammerstone/airdrop needs updating: composer.json, composer.lock, Docker images built with vendor cached, Renovate/Dependabot rules, CI cache keys, and any internal docs or scaffolds. Search your repos for hammerstone/airdrop and for the old PSR-4 namespaces before assuming you're done.
• Custom trigger classes must be re-namespaced. If you subclassed or wrote your own triggers, update the use statements to the wilbergroup namespace — stale imports will either fatal or, worse, silently fall out of discovery so your watched paths stop including them.
• Published config referencing old class strings will break. If config/airdrop.php contains fully-qualified class names (custom triggers, extensions), those strings still point at aaronfrancis/hammerstone namespaces. Republish and diff the file, or grep for the old namespace.
• One-time rebuild on first v2 deploy is expected. Trigger class names feed into the build hash, so the computed hash changes on upgrade and the very first deploy rebuilds assets once, then resumes skipping. Don't page anyone or roll back — just don't schedule the upgrade during a change freeze where an unexpected build is expensive.
• Shallow clones break the diff. If CI checks out with fetch-depth: 1, Airdrop has no reference commit to compare against. Configure the base ref explicitly or ensure the previous SHA is fetched before running the check.
• Untracked / generated files aren't seen. Files added to .gitignore (or not yet committed) typically won't trigger a rebuild. Commit config changes; don't rely on locally-built assets being detected in CI.
• Lock file changes are the classic miss. A package-lock.json bump should always force a rebuild — verify it's in the watched list before trusting the skip in production.
• Fail open, not closed. If the check errors, the safe behaviour is to build. Wrap the conditional so an Airdrop failure still runs the build; a false negative here ships stale CSS/JS to users.
• Dev-only dependency. Keeping it in require-dev means it won't load in production if you use composer install --no-dev. If your deploy runs the check after installing with --no-dev, the command won't exist. Either run it earlier or install with dev deps in the build stage.
• Don't use it as your only safety net. Airdrop optimises; it doesn't verify that public/build is present and correct. Pair the skip with a cheap sanity check (manifest exists, expected entrypoint hash matches) for high-stakes deploys.
• Extension points: the config file and the command class are the two places to hook into — override watched paths for non-standard layouts, and extend the command if you need custom output or exit codes in your deploy script.
• Debugging a wrong skip: run the check with verbose output (-v) and compare the configured base ref to the SHA your CI actually checked out. Nine times out of ten the two disagree — and after a version bump, check the hash first before suspecting your git refs.