Filakitv4 Laravel Package

Getting Started

filakitv4 is a Laravel + Filament v4 starter kit, not a runtime library you composer require into an existing app. Day one looks like:

composer create-project jeffersongoncalves/filakitv4 my-app
# or: git clone … && composer install && cp .env.example .env && php artisan key:generate
pnpm install && pnpm build
php artisan migrate --seed
php artisan serve

Then log in at /admin with the seeded credentials from your seeder/env.

Where to look first, in order:

1. app/Providers/Filament/*PanelProvider.php — the panel definition (path, guard, colors, discovery paths, middleware). Almost every "why doesn't my page show up" question is answered here.
2. The user / admin packages pulled in as of 4.14.0 — the User/Admin models, their Filament resources and the login flow now live there rather than in app/Models and app/Filament. Read those before editing anything auth-related.
3. config/auth.php + panel guard — the panel's ->authGuard() must line up with the provider the package ships.
4. vite.config.js, resources/css/filament/** — the panel theme pipeline.

First real use case: generate a resource against the admin panel and confirm it appears:

php artisan make:filament-resource Post --generate

If it doesn't show up, your panel's discoverResources() path doesn't cover where the generator wrote the file.

Implementation Patterns

Extend the shipped models, don't edit them. Because models/resources/login now come from the user/admin packages, customization belongs in a subclass:

namespace App\Models;

use JeffersonGoncalves\FilamentUser\Models\User as BaseUser;

class User extends BaseUser
{
    protected $fillable = [...BaseUser::FILLABLE, 'team_id'];
}

Then point config/auth.php providers and the panel guard at App\Models\User. Anything you edit directly inside vendor/ disappears on the next composer update.

Panel-per-audience. The kit's admin/user split maps cleanly onto Filament's multi-panel support: separate panel providers, separate guards, shared resources where the models overlap. Keep resource discovery paths disjoint so an admin resource can't leak into the user panel.

Publish, then own the file. For config, views and migrations:

php artisan vendor:publish --tag=filakit-config
php artisan vendor:publish --tag=filakit-migrations

Publishing is a one-time snapshot — once published, upstream changes are yours to merge by hand. Publish deliberately, not reflexively.

Theme work goes through Vite. Custom colors/typography belong in the panel's registered theme CSS plus the panel provider (->colors(), ->font()), then pnpm build. Don't hand-edit the compiled output.

Upgrade rhythm. Because the kit tracks Filament releases closely (4.14.0 is itself a Filament bump), treat composer update as a code change, not housekeeping: run the suite, run php artisan filament:optimize-clear (or optimize:clear), and rebuild assets before judging whether anything broke.

Static analysis as a guardrail. The repo runs PHPStan on PHP 8.4 in CI; mirror that locally in phpstan.neon so package upgrades surface type drift in your subclasses before deploy.

Gotchas and Tips

• Assets are the #1 post-upgrade failure. A Filament bump often means new CSS/JS. If the admin looks unstyled or Livewire behaves oddly after upgrading, run php artisan filament:assets, php artisan optimize:clear, then pnpm install && pnpm build — in that order.
• pnpm overrides moved. As of 4.14.0 they live in pnpm-workspace.yaml, not package.json (pnpms.overrides / pnpm.overrides). If you add overrides to package.json they'll be silently ignored — you'll chase a phantom dependency-resolution bug.
• shell-quote and source-map-js are patched via overrides. Don't "clean up" those entries; they're deliberate security/CVE pins. Removing them to tidy the file reintroduces the advisory.
• Cached config after panel changes. Registering a new panel, guard, or discovery path while config:cache is warm produces confusing 404s on /admin. Clear caches before debugging routes.
• Login/auth confusion. With the login flow living in the package, a mismatch between the panel's guard, the auth.php provider, and your App\Models\User subclass manifests as a redirect loop or "credentials don't match." Check all three before touching the login page.
• Publishing overwrites. vendor:publish --force will clobber your edits. Diff first; prefer subclassing over republishing.
• Seeded admin credentials are a footgun in production. The kit's seeder is for local bootstrap — gate it or replace it before any real deploy.
• Dependabot churn is expected noise. Many patch releases (like 4.14.0's bulk) are CI config, workflow standardization and grouped dependency bumps with no runtime change. Read the changelog for model/resource/auth-touching PRs specifically; ignore the rest. Pin versions if you need reproducible deploys.
• Extension point to remember: custom panel middleware and ->plugins() in the panel provider are the sanctioned hooks — far more upgrade-safe than editing package resources in place.