TenantAtlas/specs/057-filament-v5-upgrade/quickstart.md

Quickstart: Admin UI Stack Upgrade (Filament v5 + Livewire v4)

This quickstart is for validating the upgrade locally (Sail-first) and performing focused smoke checks.

Prerequisites

• Docker + Docker Compose (for Sail)
• Node.js + npm

Baseline (pre-upgrade)

Record these versions before changing dependencies so rollback is straightforward:

• Composer (from composer.json):
  • filament/filament: ^4.0
  • livewire/livewire: transitive (will become ^4 when upgrading to Filament v5)
  • pepperfm/filament-json: ^4
  • lara-zeus/torch-filament: ^2.0
• Frontend (from package.json):
  • vite: ^7.0.7
  • tailwindcss: ^4.0.0
  • @tailwindcss/vite: ^4.0.0

Local Setup (Sail-first)

From repo root:

• Start containers: ./vendor/bin/sail up -d
• Install PHP dependencies: ./vendor/bin/sail composer install
• Install JS dependencies: npm install
• Run migrations: ./vendor/bin/sail artisan migrate
• Build assets: npm run build (or npm run dev while iterating)

Focused Validation Checklist

1) Admin UI smoke

• Sign in.
• Load the Filament dashboard.
• Open at least one resource list/table and one resource form, and save a non-destructive edit.

2) Monitoring → Operations guardrails (DB-only)

Goal: everything under Monitoring → Operations must stay DB-only during render and during background Livewire requests.

Manual smoke:

• Open Monitoring → Operations page.
• Leave the page open while:
  • a global widget polls (Ops UX progress widget), and
  • Livewire components hydrate.
• Verify no remote HTTP calls are triggered by rendering or background Livewire requests.

Implementation verification guidance (for the later implementation phase):

• Add a targeted Pest feature test that uses Http::fake() and asserts no requests were sent while rendering Monitoring pages.

3) Tenant isolation sanity

• Switch tenant using the app’s tenancy switcher.
• Re-open Monitoring → Operations.
• Verify all visible runs are scoped to the selected tenant.

Tests

Run the minimum relevant tests first:

• Single file: ./vendor/bin/sail artisan test tests/Feature/...
• Filter: ./vendor/bin/sail artisan test --filter=...

Formatting

Before finalizing implementation:

• ./vendor/bin/sail php ./vendor/bin/pint --dirty

Common Issues

Migrations note

• The Filament v5 / Livewire v4 upgrade does not introduce new vendor-required migrations.

• If you see pending app migrations (e.g. 2026_01_18_000001_drop_bulk_operation_runs_table), apply them as usual with ./vendor/bin/sail artisan migrate.

• Vite manifest errors after upgrading dependencies: run npm run build (or npm run dev) and refresh.

• Browser caching after deploy: hard refresh / clear cache to pick up new Filament/Livewire assets.

Rollback (fast path)

If the Filament v5 / Livewire v4 upgrade needs to be reverted in a hurry:

1. Revert dependency files to a known-good commit (or restore the pre-upgrade versions):

• composer.json + composer.lock
• package.json + lockfile

2. Re-install dependencies and rebuild assets:

• ./vendor/bin/sail composer install
• npm install
• npm run build

3. Clear caches (especially if a removed package/provider was involved):

• ./vendor/bin/sail artisan optimize:clear

4. If Filament assets/config were published in the upgraded state, re-publish for the rolled-back version (only if needed):

• ./vendor/bin/sail artisan vendor:publish --tag=filament-assets --force