Dependencies

Flowery has five dependency trees: Composer at the root (Laravel), and npm at the root (the control panel), in storefront/, in landing/ and in docs/ (all three Astro). This page is the policy for keeping them current (ADR-023). The rules are few; the point is that updates arrive in small steps on a schedule rather than in a pile when something breaks.

The rules

1. An advisory is fixed within two working days. CI’s audit job fails on any advisory at moderate or above in any tree (quality checks), and Dependabot opens a pull request for it the day it is published. Fix it with a lock-only update in its own pull request; when no in-range version fixes it, use a composer.json or package.json overrides entry and say so in the changelog. Found-and-fixed advisories are recorded on the quality page.
2. In-range updates land weekly. Every Monday Dependabot opens one grouped pull request per tree with the minor and patch updates (.github/dependabot.yml). They are merged the same week after the gate (below); a group that fails the gate is split and the failing package is held with a note in the pull request.
3. Majors are planned, one framework at a time. Dependabot does not propose them. On the quarterly review (next: January 2027) the available majors are listed in PROJECT_STATE.md under “Dependencies” with a decision each: do now, do after X, or skip this cycle and why. Each major gets its own pull request, done against the upstream upgrade guide, with the full gate and a browser pass of the screens it touches. Pairs that must move together move together: Inertia’s server and client packages, Astro and its integrations, React and its type packages.
4. Production’s runtimes bound the versions. A dependency that needs a newer PHP or Node than production runs cannot be adopted until production is upgraded, whatever the audit says. The bounds today are PHP 8.4 (Forge, php8.4) and Node 22.21 (the Forge server, shared with other sites). CI tests on the same PHP; NODE_VERSION in ci.yml is 22. Astro past 7.3 needs Node 22.23.4, so the three Astro trees are pinned to ~7.3 (deployment) and dependabot.yml ignores astro >= 7.4 in each of them: a pin alone does not stop Dependabot, which raises the range (its first run, on 26 October 2026, proposed 7.4.2 in all three trees; CI’s three Astro builds went red, as they should, and the ignore rule was added). The pins and the ignore rules come off in the same change that upgrades Node on the server and in ci.yml. GitHub Actions are versioned by major tag, so their monthly group carries majors; CI running on the change is their test.
5. Every update goes through the gate. A Dependabot branch is checked out, scripts/check-all --stamp is run on it and it is merged like any other pull request (ADR-012); the release is confirmed afterwards. Nothing auto-merges.

Each week

# On the Dependabot branch:
git fetch origin && git checkout dependabot/<ecosystem>/<group>
composer install && npm ci            # whichever tree the branch touches
scripts/check-all --stamp             # every CI check, then the stamp
gh pr merge --merge                   # then confirm /release matches main

When nothing arrived, a quick look is still worth a minute:

composer outdated --direct            # Composer, direct dependencies only
npm outdated                          # root; repeat in storefront/, landing/, docs/
composer audit --locked && npm audit --audit-level=moderate

Each quarter

1. List the available majors per tree (composer outdated --direct --major-only, npm outdated shows them in the Latest column) in PROJECT_STATE.md with a decision each.
2. Check the runtime bounds: PHP and Node versions on the server (php8.4 -v, node --version over SSH), the framework’s supported range (Laravel’s support policy: bug fixes for 18 months, security fixes for two years per major) and Astro’s engines.
3. Do the chosen majors, one pull request each, in dependency order (runtime first, then the framework, then the integrations that follow it).
4. Record what was decided and what was deferred on the roadmap.

Doing a major

Laravel. Read the upgrade guide for the target version end to end. Raise laravel/framework and the first-party packages that follow it (Fortify, Pint, Sail, Tinker, Wayfinder, MCP) in one composer update with the constraint changes; run the test suite, inventory:reconcile on a fresh seed and the race suite; read the deprecation log channel. A change in session, cookie or encryption defaults goes through the deployment page’s list before the merge. Laravel Shift is an acceptable first pass; its pull request is reviewed and finished by hand.

Inertia. Server (inertiajs/inertia-laravel) and client (@inertiajs/react) move in one pull request; the SSR entry (resources/js/ssr.tsx) and HandleInertiaRequests are the places that break. Browser-test a page load, an Inertia visit, a form error and Inertia::location() across hosts.

Astro. storefront/, landing/ and docs/ can move separately; each has its own integrations (@astrojs/node and @astrojs/react in the storefront, Starlight in the docs). Check engines first (rule 4). The storefront’s theme boundary check, SDK check and Vitest suite are the gate; the docs build is the docs’ gate; the landing page gets a Lighthouse rerun.

React, Vite, TypeScript, ESLint. React and its two type packages together; Vite with laravel-vite-plugin and @vitejs/plugin-react; TypeScript with typescript-eslint; ESLint with @eslint/js and globals. Each in its own pull request, with npm run types, npm run lint:check and the build as the gate.

Where the state lives

• .github/dependabot.yml: the schedule, the grouping and the major exclusion.
• PROJECT_STATE.md “Dependencies”: the versions in use, the majors available and the decision on each.
• Quality checks: the audit job and the advisories it has caught.
• Deployment: the runtime bounds and how an over-bound lockfile fails a deploy.
• Security: why the policy exists.

Dependabot’s version updates start from the configuration file alone. Its security alerts and security pull requests are a repository setting (“Dependabot alerts” and “Dependabot security updates” under the repository’s Security settings) that the owner turns on; until then the CI audit is the only advisory signal, and it fires only when something runs.