ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
ccfd491260
TenantAtlas/specs/057-filament-v5-upgrade/quickstart.md
ahmido 971105daa9 057-filament-v5-upgrade (#66) 
Summary: Upgrade Filament to v5 (Livewire v4), replace Filament v4-only plugins, add first-party JSON renderer, and harden Monitoring/Ops UX guardrails.
What I changed:
Composer: upgraded filament/filament → v5, removed pepperfm/filament-json and lara-zeus/torch-filament, added torchlight/engine.
Views: replaced JSON viewer with json-viewer.blade.php and updated snapshot display.
Tests: added DB-only + tenant-isolation guard tests under Monitoring and OpsUx, plus Filament smoke tests.
Specs: added/updated specs/057-filament-v5-upgrade/* (spec, tasks, plan, quickstart, research).
Formatting: ran Pint; ran full test suite (641 passed, 5 skipped).
Validation:
Ran ./vendor/bin/sail artisan test (full suite) — all tests passed.
Ran ./vendor/bin/sail pint --dirty — formatting applied.
Ran npm run build locally (Vite) — assets generated.
Notes / Rollback:
Rollback: revert composer.json/composer.lock and build assets; documented in quickstart.md.
One pending app migration was noted during validation; ensure migrations are applied in staging before deploy.
Reviewers: @frontend, @backend (adjust as needed)
Spec links:
spec.md
tasks.md
quickstart.md

Co-authored-by: Ahmed Darrazi <ahmeddarrazi@adsmac.local>
Reviewed-on: #66
2026-01-20 21:19:27 +00:00

3.4 KiB
Raw Blame History

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
  1. Re-install dependencies and rebuild assets:
  • ./vendor/bin/sail composer install
  • npm install
  • npm run build
  1. Clear caches (especially if a removed package/provider was involved):
  • ./vendor/bin/sail artisan optimize:clear
  1. 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