Superduper Filament Starter Kit Laravel Package

Getting Started

1. Bootstrap the project — composer create-project riodwanto/superduper-filament-starter-kit my-app, then cp .env.example .env, php artisan key:generate, configure DB_*, php artisan migrate --seed, php artisan storage:link, npm install && npm run dev, php artisan serve.
2. Log into the panel — visit /admin and sign in with the seeded super-admin (check database/seeders/DatabaseSeeder.php for the exact credentials; usually [email protected] / password — change immediately).
3. Where to look first — in this order:
   • app/Providers/Filament/AdminPanelProvider.php — the panel is registered here; plugins, middleware, colors, and navigation all hang off this file.
   • app/Filament/Resources/ — every pre-built CRUD (Users, Roles, Posts, Pages, Media, Settings).
   • config/ — plugin configs: filament-shield.php, filament-curator.php, filament-spatie-media-library.php, settings.php, SEO config.
   • resources/views/ and routes/web.php — the front site, Blade components, and theme tokens.
4. First real use case — add a “Projects” content type: php artisan make:filament-resource Project --generate, define the form/table, then php artisan shield:generate --all so the new resource appears in permissions. That single loop (resource → policy → nav → front-end route) is the daily rhythm of the kit.

Implementation Patterns

• Resource-centric CRUD. Almost everything in the admin is a Filament Resource. Model + Resource + Pages + RelationManagers is the standard unit. Use php artisan make:filament-resource X --generate --view and then trim the generated form to the fields you actually need.
• Shield-driven authorization. Roles and permissions come from Filament Shield + Spatie Permission. Every new Resource, Page, or Widget needs php artisan shield:generate --all (or targeted --option=resources). Wire policies into AdminPanelProvider via ->plugins([FilamentShieldPlugin::make()]) — never hand-write can() checks that bypass Shield.
• Media via Curator + Spatie Media Library. Add HasMedia + InteractsWithMedia to the model, register a collection in registerMediaCollections(), and use the CuratorPicker form field in the Resource. Uploads land under the configured disk — keep them going through Curator so conversions, focal points, and the media manager stay consistent.
• Settings via Spatie Settings. Site name, logo, theme colors, footer text, SEO defaults, etc. live as Settings classes (typically under app/Settings/). Edit them through the Filament settings pages; read them anywhere with app(GeneralSettings::class)->site_name. Cache them — spatie/laravel-settings is cache: false by default, so enable caching in the config.
• Content management pattern. Posts/Pages follow a model → Resource → front-end Blade route shape: Post has slug, status, published_at, featured media, SEO meta. Use mutateFormDataBeforeCreate / mutateFormDataBeforeSave for derived fields (slug, author, reading time) instead of putting that logic in the model.
• Front site integration. The front-end is Blade + Tailwind, often with Livewire islands. Theme values (primary color, font, radius) are Tailwind CSS variables set from Settings; override via tailwind.config.js tokens, not hardcoded hex. Front routes typically live in routes/web.php and resolve models by slug with route-model binding.
• SEO fields. Form fields write to the SEO columns / ralphjsmit/laravel-seo-style meta table. Rendering happens in the front layout <head> — add @yield('meta') / @stack('seo') (or the equivalent component) to resources/views/layouts/app.blade.php so per-page meta actually emits.
• Navigation & scale. Group resources with ->navigationGroup('Content'); use ->cluster() when the admin grows past ~15 resources. Register dashboard widgets once in the panel provider so the overview stays composable.
• Extend, don't fork. Prefer subclassing or extending the shipped Resources and Pages, and publish a config with php artisan vendor:publish --tag=filament-... when you need to change behavior. Keep changes in app/ and resources/ so future kit updates remain mergable.

Gotchas and Tips

• Shield permissions are stale by default. Any new Resource/Page/Widget is invisible to non-super-admins until you re-run php artisan shield:generate --all and assign the permission to a role. This is the #1 “it works for admin but not for editor” bug.
• Cache-bust after plugin/config edits. php artisan optimize:clear (or filament:optimize-clear) after touching panel providers, Shield, or config. In production run php artisan filament:optimize to cache components and icons.
• Filament version pinning. Filament v3 and v4 plugins are not interchangeable. Check composer.json for the pinned Filament version before adding any third-party plugin, and match its constraint.
• Media storage gotchas. php artisan storage:link is required, and the Curator/media disk must match FILESYSTEM_DISK. If images 404 in production, it’s almost always the symlink or a missing public disk config.
• Seeded admin is a footgun. The default super-admin exists in seeders with known credentials. Rotate or delete it before any non-local deploy.
• Slug collisions. Filament’s Slug field has generateUniqueSlug(); if you build slugs manually, add a model observer or unique validation rule. Silent Str::slug() overwrites are painful once URLs are live.
• SEO won’t render if the layout is untouched. The form fields persist fine, but output only appears where the layout emits meta tags. Verify with curl | grep '<meta' rather than trusting the admin preview.
• Front-end theme drift. Colors set in Settings need to flow through Tailwind tokens. If you hardcode bg-blue-600 in a Blade file, changing the theme in admin won’t affect it — always use the CSS variable (bg-primary).
• Livewire discovery. New Livewire components on the front site need php artisan livewire:discover (or correct namespace registration) before they render.
• N+1 in tables. Filament tables lazy-load relations. Add ->modifyQueryUsing(fn ($q) => $q->with(['author', 'media'])) on the table to avoid per-row queries at scale.
• Extension points worth memorizing: AdminPanelProvider::panel() (nav, colors, middleware, plugins), resource hooks (mutateFormDataBeforeCreate, afterCreate, getNavigationBadge), FilamentShieldPlugin config, and the Settings classes. Nearly every customization request routes through one of these.
• Debugging: php artisan filament:about prints installed panels, plugins, and versions — start there when a plugin “isn’t showing up.” Livewire DevTools in the browser is invaluable for form/action misbehavior.
• Never edit vendor/. If a behavior is wrong, publish the config or extend the class; the kit ships updates regularly and vendor edits will be wiped.