ckn01/superduper-filament-starter-kit
A Laravel starter kit for Filament that scaffolds admin panel resources, pages, and sensible defaults, helping you bootstrap back-office interfaces faster with an opinionated setup for new projects.
Treat this as a template you fork, not a Composer dependency you require. There is no runtime API to learn — the value is the pre-wired panel, theme, roles, and mail config you inherit on day one.
Bootstrap path (new admin surface):
git clone https://github.com/ckn01/superduper-filament-starter-kit.git my-admin
cd my-admin
composer install
cp .env.example .env && php artisan key:generate
# edit .env: DB_*, MAIL_*, APP_URL
php artisan migrate --seed
npm install && npm run build
php artisan serve
Then log in at /admin with the seeded super-admin account (check database/seeders/ — the credentials are in the seeder, which is your first read).
If you'd rather graft it onto an existing app: clone into a scratch directory, copy app/Providers/Filament/, app/Filament/, the theme CSS under resources/css/filament/, the Shield config, and the relevant migrations/seeders — do not copy composer.json/package.json wholesale, or you'll fight version constraints.
Read these first, in order:
app/Providers/Filament/*PanelProvider.php — path, colors, middleware, theme registration, plugin list. This is the control panel for the whole kit.config/filament-shield.php + the role/permission seeder — how authorization is actually wired.resources/css/filament/**/theme.css — the custom theme entrypoint.database/seeders/ and database/factories/ — the demo resources and users.First real use case: generate one resource against the seeded schema and confirm it appears with correct permissions.
php artisan make:filament-resource Customer --generate
php artisan shield:generate --all
php artisan permission:cache-reset
Log in as the seeded super-admin, then create a non-super-admin user with a limited role and verify the nav items disappear. That single loop validates auth, roles, theme, and navigation in one pass — do it before writing any domain code.
Panel configuration lives in the provider, not config files. Customize branding, colors, nav groups, and path there:
->brandName('Acme Ops')
->colors(['primary' => Color::Emerald])
->path('ops') // moves the panel off /admin
->navigationGroups(['Sales', 'Settings'])
->viteTheme('resources/css/filament/admin/theme.css')
Change the path early — it leaks into URLs, emails, and tests.
Role/permission workflow is a three-step loop, and you must run all three. Adding a resource without regenerating permissions is the #1 "why can't this user see it" bug:
php artisan make:filament-resource Invoice --generate
php artisan shield:generate --all # creates permissions for the new resource
php artisan permission:cache-reset # clears spatie's cache
Encode the roles you actually care about (super_admin, ops, readonly) in a seeder so every environment — CI included — starts consistent. Avoid hand-assigning permissions in the UI for anything that must reproduce.
Resources + policies are the day-to-day unit of work. For anything beyond CRUD, generate the policy explicitly (--policy) rather than relying on Shield's generated defaults, then layer Filament's visibility methods on top:
public static function canViewAny(): bool
{
return auth()->user()->can('view_any_invoice');
}
Keep authorization in the policy and use visible()/->hidden() only for cosmetic filtering.
Theme changes go through Vite, not inline CSS. Edit theme.css, register it via ->viteTheme(...), then npm run build before deploying. Tailwind classes added inside Filament resource views are only compiled if the theme file's content globs cover app/Filament/** — check the theme's @source/content config if a class silently does nothing.
Mail is env-driven — keep it that way. The kit's mail configuration should read from MAIL_*; resist hardcoding transports in a service provider. For per-panel or per-tenant mailers, define named mailers in config/mail.php and select with Mail::mailer('tenant'). Locally use Mailpit/log driver; in tests, Mail::fake() and assert — don't let a seeded config point at a real SMTP host.
Exception/reporting plugin: register it in the panel provider and gate it. It's an operator tool. Make sure only super_admin (or a dedicated role) can reach it, and confirm it doesn't render stack traces or env values to ordinary admins. That's a production security decision the starter kit can't make for you.
Seeds and factories are for local + CI, not prod. Use them to build deterministic tests (RefreshDatabase + seeders) and to onboard new devs. Never run migrate --seed against production without first auditing the seeders for known-password demo users.
Extension points worth knowing: the panel provider (plugins, middleware, nav), Panel ->userMenuItems(), resource getNavigationGroup(), custom Livewire widgets in app/Filament/Widgets, and Shield's Gate::before super-admin bypass. Most customization is composition here, not patching vendor code.
Multi-panel: if you need a separate admin and customer surface, add a second PanelProvider via php artisan make:filament-panel, reuse the theme, and split Shield roles by panel guard — but do this before you have 40 resources, not after.
git pull upstream will conflict with every customization. Decide up front: (a) hard fork, own it forever, or (b) cherry-pick patterns and keep your own repo. Record the commit you forked from in your README.composer show filament/filament laravel/framework immediately after install and write those versions into a compatibility note. v1.0.6 (Aug 2024) predates later Filament 3.x minors — expect to review the changelog before bumping.php artisan permission:cache-reset, and check the permission naming convention (view_any_, create_, snake_case of the model) matches what your policy actually checks.Gate::before grants everything to super_admin, your authorization tests are meaningless when run as that user. Write permission tests as a scoped role user, always..env. The kit ships mail and panel config that read env. After editing .env locally, php artisan config:clear. In production, config:cache during deploy — and verify MAIL_* and APP_URL are present before caching, since a misconfigured cached config is invisible until mail silently fails.npm run build show nothing. Published Filament assets occasionally need php artisan filament:assets after an upgrade. When styling "randomly reverts," suspect the build, not the CSS.php artisan about (env/version sanity), php artisan route:list --path=admin (panel routing), storage/logs/laravel.log for Livewire exceptions that surface as a generic toast, and php artisan filament:optimize / filament:optimize-clear when component caching behaves oddly in production.How can I help you explore Laravel packages today?