Nativekitv4 Laravel Package

Getting Started

This is a Filament v4 application kit (a scaffold, not a drop-in library) — you get a working admin + user app rather than a package you composer require. As of 4.14.0 it pins Filament v4.14.0 and splits models/resources/login into separate user and admin concerns, so expect two auth surfaces out of the box.

Minimal path to a running app:

git clone <repo> my-app && cd my-app
composer install
cp .env.example .env && php artisan key:generate
# set DB_* in .env
php artisan migrate --seed
pnpm install && pnpm build      # or: pnpm dev
php artisan serve

Look here first, in this order:

1. app/Providers/Filament/ — one panel provider per surface (admin vs user). This is the source of truth for paths, guards, login, colors, and resource discovery.
2. The user/admin model + resource namespaces introduced in 4.14.0 (PR #95). Confirm which model backs which guard before writing any query.
3. config/auth.php — guards and password brokers must match the panels, or logins silently bounce.
4. routes/ + the panel providers' ->login() / ->path() — admin typically lives at /admin, user at /.

First use case: log into /admin with the seeded admin, then scaffold one resource end-to-end (php artisan make:filament-resource Post --panel=admin) and place it in the admin namespace. That single loop teaches you the split faster than reading the codebase.

Implementation Patterns

Work per panel, not per app. The 4.14.0 user/admin split is the organizing principle. Treat each surface as its own bounded context:

• Resources, pages, widgets, and policies for admin belong in the admin namespace/package.
• End-user-facing screens (profile, dashboard, own-record CRUD) belong in the user one.
• Shared behaviour goes in a trait or base model, not by pointing both panels at one model.

Resource scaffolding into the right namespace. The generator writes to the default location; in the split layout you usually move or re-namespace the file immediately:

php artisan make:filament-resource Invoice --panel=admin --generate
# then relocate to your Admin resources namespace and fix the namespace line
composer dump-autoload

Two guards, two password brokers. Configure config/auth.php with distinct providers/brokers for admin and user, and bind each panel:

// AdminPanelProvider
->authGuard('admin')
->login()
->path('admin')

// UserPanelProvider
->authGuard('web')
->login()
->path('')

Anything that touches auth()->user() inside a shared Livewire component should read the panel's guard explicitly (Filament::auth()->user()) rather than relying on the default.

Sharing data across the split. If both surfaces reference the same domain records, define relationships against explicit model classes and keep foreign keys on a single users-style table unless you deliberately created two. Decide early — retrofitting a second users table after launch is the expensive path.

Frontend changes in 4.14.0. pnpm overrides moved from package.json into pnpm-workspace.yaml, and shell-quote / source-map-js are patched there. Keep app-specific overrides in the workspace file too — mixing sources produces "why is this version installed" afternoons. Vite is now 8.3.1; commit the lockfile and use pnpm install --frozen-lockfile in CI.

Copy the CI shape, don't invent one. The release standardizes dependabot config, a tests workflow, and PHPStan on PHP 8.4. If you're building on this kit, lift those workflows wholesale — static analysis on 8.4 while running 8.2/8.3 in prod is a fine split, and the dependabot grouping saves a lot of PR noise.

Gotchas and Tips

The model split is the migration risk, not the version bump. Filament 4.13.4 → 4.14.0 is minor, but PR #95 changes which class backs admin resources and login. If you're upgrading an existing app built on 4.13.x:

• Diff your PanelProvider files against upstream before pulling — auth guard and resource discovery lines are exactly what changed.
• php artisan filament:cache-components (or optimize:clear) after moving resources; stale component caches surface as "page not found" inside panels.
• Any relation typed to the old single User will now type-mismatch. Grep for User::class across policies, factories, seeders, and belongsTo calls.
• Password hashes and remember tokens don't survive a guard swap. Re-seed or force a re-login rather than debugging "invalid credentials" that are actually fine.

Filament upgrade checklist. After any Filament bump: php artisan filament:upgrade (publishes assets/config), php artisan filament:assets, then php artisan optimize:clear. Skipping the asset step gives you styled-broken forms that look like a bug in your code.

Registering resources that live outside app/. If resources sit in a package namespace, either implement a plugin's register() or add them to discoverResources(). Filament will not pick them up by convention alone, and the failure mode is a silently empty nav.

pnpm override conflicts. If your app's package.json still has a pnpm.overrides block, it now competes with the workspace file. Symptoms: patched versions reverting after pnpm install, or vite build succeeding locally and failing in CI. Verify with:

pnpm why shell-quote
pnpm why source-map-js

PHP 8.4 in CI ≠ PHP 8.4 required. The PHPStan job moved to 8.4 runner; check composer.json require.php before assuming you can drop 8.2 support or use 8.4-only syntax.

Debugging tips that pay off here:

• php artisan about confirms which panel providers and guards are actually loaded.
• php artisan route:list --path=admin proves the panel registered with the path you expect.
• When a login form posts and nothing happens, check the panel's authGuard() first — the credentials are usually fine and the guard is wrong.
• Livewire component errors inside a panel often mean a resource moved namespaces after the component cache was built.

Extension points worth knowing before you fork anything: custom PanelProvider subclasses, a custom theme via ->viteTheme() for per-surface styling, published views (php artisan vendor:publish --tag=filament-views) for layout tweaks, and Filament plugins for anything cross-cutting (impersonation, audit logs) so you don't hand-roll it twice across the split.