Filament Starter Kit Laravel Package

Getting Started

This is a starter kit / project template, not a library you composer require into an existing app. Day-to-day usage starts with materialising it as your application skeleton.

1. Create the project from the repo (GitHub "Use this template" or git clone + re-init the remote), then:

   composer install
   cp .env.example .env && php artisan key:generate
   php artisan migrate --seed
   npm install && npm run build   # or npm run dev
   

2. Log in at /admin with the credentials created by the seeder (check database/seeders/ — change these before anything else).
3. Look here first:
   • app/Providers/Filament/*.php — panel configuration, path, auth guard, colours, middleware.
   • app/Filament/Resources/ and app/Filament/Pages/ — the existing User/role/settings screens.
   • composer.json — the pinned Filament major, Shield, and permission package versions; these dictate what plugin versions you can add later.
   • vite.config.js + resources/css/app.css — the asset pipeline changed shape in this release cycle (see Gotchas).
4. First real use case: model one of your own domain entities end-to-end — migration → Eloquent model → php artisan make:filament-resource Invoice --generate → expose it in the panel navigation, then generate its permissions with Shield and verify a non-super-admin role can only see what it should.

Implementation Patterns

Treat it as a fork, not a dependency. Because it is a template, upgrades are a manual git diff against upstream, not composer update. Keep a short changelog of what you changed in the panel provider and theme so future merges are tractable.

Build outward from the existing resources. The bundled User/role screens are the reference implementation for form schemas, table filters, policies, and relationship managers. Copy their conventions (policy registration, getNavigationGroup(), action placement) rather than inventing new ones — consistency is the main payoff of a starter kit.

Roles and permissions loop (Shield). The repeatable workflow per feature:

php artisan make:filament-resource Invoice --generate
php artisan shield:generate --all --panel=admin   # after adding/renaming resources
php artisan permission:cache-reset

Then assign permissions to roles in the UI. Make this a step in your PR checklist; forgetting it is the single most common cause of "the menu item is there but 403s."

Panel composition. Register widgets and extra pages in the panel provider rather than editing vendor views. For a second panel (e.g. a customer-facing area), duplicate the provider with its own ->id(), ->path(), guard, and colour palette; Shield supports --panel scoping for permissions.

Theme customisation. Fork the panel theme rather than overriding Filament's CSS ad hoc: register a custom theme in the panel provider, point Vite at your resources/css/filament/admin/theme.css, and layer your brand tokens there. Anything you put in resources/css/app.css alongside it is your app CSS, not the panel's.

Deployment shape. npm run build on the build host, ship public/build, then php artisan migrate --force && php artisan optimize and php artisan filament:upgrade / php artisan icons:cache in your release script. Run Shield generation as a deploy step only if permissions are code-driven in your setup; otherwise run it manually and commit the seeder changes.

Seeders as onboarding. Extend the existing seeders so a fresh migrate --seed yields a usable environment (admin user, base roles, reference data). This is what makes the kit fast to spin up for a new project.

Gotchas and Tips

Release 1.1.0 is dependency churn only. Every entry is a Dependabot bump — GitHub Actions versions (checkout, cache, setup-node, git-auto-commit) and JS toolchain (axios, vite/laravel-vite-plugin/@tailwindcss/vite, form-data, postcss). There are no PHP API changes, no deprecations, no migration steps. Safe to take; nothing in your application code needs to react to it.

But the Vite/Tailwind bump is not cosmetic if you haven't built yet. Pulling @tailwindcss/vite plus a current laravel-vite-plugin means Tailwind v4-style, CSS-first configuration:

• tailwind.config.js may no longer exist or may be largely irrelevant — look for @import "tailwindcss", @theme, @source, and @plugin directives in your CSS instead of a JS config object.
• In vite.config.js the Tailwind plugin must be registered before the Laravel plugin.
• Plugins previously added in JS config now load via @plugin "..." in CSS.
• If styles silently vanish, delete node_modules/.vite and rebuild before debugging anything else.

Node version floor moved. Current Vite releases require Node 20.19+/22.12+. If CI or a teammate's machine is on Node 18, npm run build fails with a confusing syntax/ESM error rather than a clear version message. Pin Node in CI and in .nvmrc.

GitHub Actions bumps are invisible at runtime but will break your fork's workflows if you pinned action SHAs or rely on old input names — check .github/workflows/ after merging upstream, and note Dependabot PRs will now be authored against the new majors.

Permissions go stale after refactors. Renaming a resource or policy silently orphans permissions. Symptom: super-admin sees everything, other roles see nothing. Fix: shield:generate --all then permission:cache-reset.

Seeded credentials are a live risk. The kit ships a known admin login. Rotate it in every environment before exposing the panel; consider gating the seeder behind app()->environment('local').

Uploads need the symlink. File/image fields fail with 404s until php artisan storage:link runs. Easy to forget on a fresh clone.

Asset/panel cache drift after composer updates. If the panel renders unstyled or icons disappear, run php artisan filament:upgrade and php artisan icons:cache, then php artisan optimize:clear.

Debugging routine: php artisan about (env, cache, driver sanity) → php artisan optimize:clear → check APP_DEBUG and Filament's own config for verbose errors → for 403s specifically, verify the policy is auto-discovered and that the user's role actually carries the generated permission. Extension points to prefer over vendor edits: panel provider, custom theme CSS, policies, resource/table/form ->modify… closures, and Filament render hooks.