Filament 5 Upgrade Guide for Livewire 4 Apps

An admin panel upgrade is complete when editors can reliably finish their work. Installing the new dependencies is one part of that change. The rest is proving that a user can sign in, find a record, edit it, upload a file, and save the intended result with the correct permissions.

Filament’s January 2026 announcement explains that the v5 release introduced Livewire 4 support. At launch, that integration was the difference from v4. For an existing application, custom Livewire behavior therefore deserves particular attention.

Check the application you actually have

The Filament 5 upgrade guide lists PHP 8.2+, Laravel 11.28+, Livewire 4+, and Tailwind CSS 4+ as requirements. Other application dependencies may impose higher minimums. Review the complete Composer graph rather than treating one package’s minimum as the application’s target.

composer show filament/filament
composer show livewire/livewire
composer prohibits filament/filament '^5.0'

Inventory panel plugins and custom integrations before changing constraints. For each plugin, record the installed version and the maintainer’s declared compatibility. When a required plugin blocks the upgrade, resolve that dependency explicitly. Removing a feature changes the product and should be a deliberate decision.

Use the official migration tool, then review its work

From a committed working tree, the documented starting commands are:

composer require filament/upgrade:"^5.0" -W --dev
vendor/bin/filament-v5

Follow the commands that the script prints for your application and review the resulting changes. The guide also directs applications with custom Livewire code to the Livewire upgrade guide. Finish dependency resolution and asset compilation before opening the panel for verification.

Review custom Livewire behavior deliberately

Use the Livewire 4 upgrade guide alongside the Filament guide when reviewing custom components. Make an inventory of your own JavaScript hooks, nested components, and custom form inputs, then map each one to a workflow that exercises it.

For example, a custom image picker may open correctly while failing to update its parent form. Test selecting an image, replacing it, clearing it, and saving each state. If an integration listens for an event, check the documented event behavior and inspect the actual request. A panel screenshot alone cannot establish that the data reached the component that owns the save operation.

Review the migration diff in small groups: dependency constraints, generated PHP changes, custom component changes, and frontend assets. Explain any manual change in terms of the failing workflow it repairs. This makes the review tractable and helps prevent an upgrade from becoming an unrelated redesign of every resource in the application.

Choose a small set of complete workflows

For a course platform, use an article with rich content, a course with several episodes, and an account with restricted access. These examples exercise different parts of the panel and are easier to reason about than clicking through every navigation item without a purpose.

Create a draft article, add formatted text and a link, save it, reopen it, and compare the persisted content.
Edit an existing public article without changing its slug; confirm its public URL still resolves to the same record.
Reorder course episodes, reload the editor, and confirm the public course follows the saved order.
Upload an image, save the record, and open the resulting image URL from a separate browser session.
Sign in as a restricted user and try both ordinary navigation and direct URLs for protected records.

Verify outcomes in the persisted record as well as the interface. A successful toast can coexist with an omitted field, a stale relationship, or an upload that points to a disk unavailable to the web server. Compare the public page with the editor whenever both render the same content.

Example: verify a public article after editing

Use a known published article and record its ID, slug, title, and public URL. Change only its title in the upgraded panel, save, and reload the editor. Then open the public URL in a separate session. This catches differences between the state visible in a component and the state another request reads from the database.

For an application with an Article model, the following read-only Tinker inspection makes that comparison explicit. Substitute the ID of your test record. The fields shown are assumptions about the example application; adapt them to the schema you actually maintain.

php artisan tinker

use App\Models\Article;

$article = Article::query()->findOrFail(42);

$article->only([
    'id',
    'title',
    'slug',
    'published_at',
]);

The expected result is the new title with the original slug and publication state. If the public page still shows the old title, investigate the application’s caching or indexing path using that record ID. Avoid repeatedly editing unrelated fields while debugging; one controlled change makes it much easier to locate the boundary where state becomes stale.

Example: check validation and restricted access

Clear a required field and attempt to save. Confirm the error is visible beside the field, keyboard focus remains usable, and the previous persisted value has not been erased. Then correct the field and save successfully. This tests the recovery path that editors will use when they make an ordinary mistake.

Next use a restricted account with a record it must not modify. Check the list view, the edit URL, and the server-side update path covered by your existing tests. For a policy test, assert the authorization result for both permitted and forbidden users. The precise setup depends on your roles and tenancy model; inventing a generic is_admin flag would obscure the rules the upgrade needs to preserve.

Make the visual review reproducible

Capture the panel at desktop width and at a narrow viewport. Include an open action modal, a validation error, a long table row, and the rich editor. Check that primary actions remain visible and keyboard focus follows the interaction. Use the same sample record before and after the upgrade so differences are easy to inspect.

For permission checks, pair the screenshots with automated assertions around the policy or protected action. Hiding a button improves the interface, but the server must still reject an unauthorized operation. A screenshot proves what was displayed; an authorization check proves what the account was allowed to do.

Verify the deployed build too

Repeat the critical editing workflow after deployment using the production asset build. Inspect browser errors and failed requests while opening forms and saving changes. Record the deployed revision beside the screenshots so that the evidence refers to the version editors will use.

Build and inspect the assets used by editors

If your project uses npm and defines the usual build script, run the project’s locked dependency installation and production build. Use the equivalent documented commands for another package manager. The relevant result is a build from the committed lock file that includes your custom theme and application JavaScript.

npm ci
npm run build
php artisan test

Run the tests required by your project and inspect failures before proceeding. An existing suite may cover policies and persistence while leaving keyboard interaction or a custom editor untested, so keep the browser checks in the release review. Conversely, a clean visual review does not justify ignoring a failing authorization test.

After deployment, use a fresh session to open an action modal, trigger validation, upload an image, and save a record. Check that the browser loads the expected compiled assets and that requests complete successfully. Capture the revision, role, viewport, and sample record beside the evidence. If a problem appears only after deployment, compare configuration and asset delivery before changing application behavior.

Keep the upgrade report short and specific: dependency versions, workflows completed, records checked, and any unresolved failure. That makes the result useful to the next person maintaining the panel and gives you a clear boundary for what has actually been verified.