Filament Starter Laravel Package

Getting Started

This is a project template, not a Composer library. Treat it as a scaffold you own from day one.

1. Create a project from the repo:
   • GitHub: Use this template → clone your new repo.
   • Or, if published: composer create-project log1x/filament-starter my-app.
2. Install and configure:

composer install
cp .env.example .env
php artisan key:generate
# set DB_* in .env
npm install
php artisan migrate --seed
npm run build
php artisan serve

3. Log in at /admin with the seeded user. Check database/seeders/DatabaseSeeder.php for credentials; change them immediately.

Look here first:

• app/Providers/Filament/AdminPanelProvider.php — panel path, auth, colors, middleware, plugins, widgets.
• app/Filament/Resources/UserResource.php — reference resource implementation.
• resources/css/filament/admin/theme.css — Tailwind/Filament theme.
• app/Models/User.php — FilamentUser::canAccessPanel() and policy wiring.
• tests/Feature — starter test patterns.
• composer.json scripts — lint, test, analyse, CI entry points.

First meaningful use case: replace the demo dashboard/User resource with your first domain resource:

php artisan make:filament-resource Customer --generate

Then refine the generated form/table, add a policy, and register navigation grouping in the panel provider.

Implementation Patterns

Resource-first development. Most day-to-day work happens in app/Filament/Resources. Use generators, then edit:

php artisan make:filament-resource Order --generate --view
php artisan make-filament-policy Order

Keep form/table schemas in the resource; move reusable fields into app/Filament/Forms/Components or app/Filament/Tables/Columns.

Panel configuration as the control plane. Use AdminPanelProvider for:

->path('admin')
->login()
->colors(['primary' => Color::Indigo])
->viteTheme('resources/css/filament/admin/theme.css')
->plugins([...])
->widgets([...])
->navigationGroups([...])
->middleware([...])

For a second panel (e.g. customer portal), generate another provider and register it in bootstrap/providers.php; don’t overload the admin panel.

Auth and authorization. Implement FilamentUser on User and gate panel access:

public function canAccessPanel(Panel $panel): bool
{
    return $this->hasRole('admin') && $this->hasVerifiedEmail();
}

Pair with policies for resources. Use seeders for local roles, but avoid hardcoding production admins in seeders.

Theme workflow. Edit resources/css/filament/admin/theme.css, then:

npm run build
php artisan filament:assets

If colors/assets look stale, run php artisan filament:optimize-clear and hard-refresh.

Widgets and custom pages. Scaffold with:

php artisan make:filament-widget StatsOverview --stats-overview
php artisan make:filament-page Settings --panel=admin

Register widgets in the panel provider or resource getHeaderWidgets(). Use custom pages for settings/profile screens instead of stuffing logic into resources.

Testing pattern. Use Pest/PHPUnit with RefreshDatabase, actingAs($user), and Livewire assertions for Filament components. Test policy boundaries and canAccessPanel() separately. Keep CI running composer test, composer lint, and composer analyse if configured.

Deployment workflow. On deploy:

composer install --no-dev --optimize-autoloader
npm ci && npm run build
php artisan migrate --force
php artisan filament:optimize
php artisan optimize

Ensure storage:link and writable storage//bootstrap/cache.

Stripping the starter. Early in a project, delete demo resources/widgets/seeders you won’t use, update navigation groups, and simplify AdminPanelProvider. The template is most useful as a reference; carrying unused demo code slows onboarding.

Gotchas and Tips

• No upstream package updates. This is a template. You won’t get composer update fixes for starter code. Upgrade Filament/Laravel manually and follow their upgrade guides; pin versions in composer.json and test upgrades.
• Assets are a common failure point. If styles are missing after install, you likely skipped npm run build or php artisan filament:assets. Custom themes must be referenced with ->viteTheme(...) in the panel provider.
• Panel access failures. If login succeeds but /admin 403s, check User::canAccessPanel(), the FilamentUser contract, email verification, and roles. Seeded users may have email_verified_at = null.
• Cached components hide new classes. In local dev, php artisan filament:cache-components can make new resources/pages invisible. Clear with php artisan filament:optimize-clear or php artisan optimize:clear.
• SQLite default vs production. The starter may default to SQLite. Switch to MySQL/Postgres early to catch migration and collation issues before deploy.
• Demo credentials are not production-safe. Change seeded users, remove demo seeders, and avoid committing .env.
• Multi-tenancy has hidden wiring. If enabling Filament tenancy, configure ->tenant(Team::class), relationships, and route binding; test tenant scoping in policies and resources. It’s easy to leak cross-tenant data if policies are incomplete.
• Don’t edit vendor. Publish config/assets when needed (php artisan vendor:publish), and use panel provider/render hooks for UI changes. Extension points include PanelsRenderHook, custom user menu items, ->brandLogo(), ->darkMode(), custom login pages, and panel middleware.
• Debugging commands: php artisan about, php artisan route:list --path=admin, php artisan filament:optimize-clear, and tail -f storage/logs/laravel.log. For Livewire/Filament component issues, inspect the browser network response and Laravel log rather than guessing.
• Keep the template lean. The starter’s value is patterns, not demo code. Strip early, document your panel conventions, and add your own generators/tests so the project stays maintainable.