105 lines
3.4 KiB
Markdown
105 lines
3.4 KiB
Markdown
# 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`
|