Superduper Filament Starter Kit Laravel Package

Getting Started

This is a starter kit, not a library you composer require into an existing app. The mental model is "fork and build," so your first decision is whether you want the whole application skeleton (front site + admin panel + CMS + SEO) or just the admin scaffolding. If you only need an admin panel, plain filament/filament is lighter; this kit pays off when you want a working front-of-site with content types and SEO fields already wired.

Bootstrap flow (names may shift between releases — check the README and composer.json scripts first):

git clone https://github.com/1odp/superduper-filament-starter-kit my-app
cd my-app
composer install
cp .env.example .env
php artisan key:generate
# configure DB in .env
php artisan migrate --seed
php artisan storage:link
npm install && npm run build
php artisan serve

Then log into /admin with the credentials defined in database/seeders. If login fails, grep the seeders for password before assuming the install is broken.

Where to look first, in order:

1. app/Providers/Filament/AdminPanelProvider.php (or app/Providers/Filament/*) — panel path, plugins, middleware, theme, auth guard. This one file explains most "why is this missing/showing" questions.
2. config/ — any kit-specific config (SEO, theme, settings). Anything you might tune lives here, not in vendor.
3. app/Filament/Resources — the canonical examples of how the kit expects you to model content. Copy the closest existing resource rather than starting from make:filament-resource.
4. resources/views + routes/web.php — how front-site pages are rendered and which Blade components/blocks the theme exposes.
5. Settings/theme screens in the admin panel — what is DB-driven vs. hardcoded in views.

First use case to validate the kit: add a new content type end-to-end — "Project" or "Case Study" — with a title, slug, rich-text body, featured image, and SEO fields. That single exercise touches the model, migration, Filament resource, front-end route, Blade view, and SEO rendering, which tells you in an hour whether the kit's conventions match your project.

Implementation Patterns

Content-type recipe (the core loop). Everything in a CMS starter kit reduces to this repeatable sequence:

php artisan make:model Project -mf
# edit migration: title, slug (unique), body, published_at, seo fields
php artisan make:filament-resource Project --generate

Then, inside the generated resource: reuse the kit's form schema conventions (sections, Grid, slug auto-generation from title, SEO field group/partial if the kit ships one), add the table columns with ->searchable() and ->toggleable(), and register a front-end route + Blade view that renders {!! $project->body !!} inside the shared layout partial that emits meta tags.

Copy, don't invent. The highest-leverage habit with any starter kit is treating existing resources as templates. If the kit ships a Post resource with SEO, media, publishing state, and permissions all correct, your second content type should be a near-clone. Diverging early is how starter kits turn into legacy code.

SEO: render from one place. The usual failure mode is SEO fields stored but never output. Find the layout/partial that renders <title>, canonical, OG, and Twitter tags, and make every front-end view extend it. If the kit ships sitemap generation, confirm new content types are registered there — a content type invisible to the sitemap is a silent bug.

Theme customization: settings first, CSS second. Prefer the admin theme/settings screen for colors, logos, and typography so changes survive deploys. For anything visual the settings don't cover, add a small custom stylesheet registered through the panel/theme provider rather than editing the kit's compiled assets directly — otherwise the next npm run build erases your work or, worse, you can't tell what's yours.

Users and permissions. The kit typically ships roles/permissions (Shield or spatie/permission) with policies generated per resource. The pattern that holds up:

• Add roles as seeders, not clicks, so environments stay reproducible.
• Extend generated policies for row-level rules ("editors only edit their own posts") in app/Policies, never in the resource.
• Guard the super-admin role against self-demotion and against deletion in the resource's canDelete()/form visibility — this is the classic lock-yourself-out bug.

Keep upstream reachable. Because there is no composer update path for the application code, add the original repo as a remote:

git remote add upstream https://github.com/1odp/superduper-filament-starter-kit.git

Then cherry-pick security or bug fixes instead of hand-diffing later. Keep your own work in commits that are easy to rebase — avoid sweeping reformatting of kit files.

Plugin additions. Register new Filament plugins and panel middleware in the panel provider so configuration stays in one auditable place; a plugin registered in a service provider and another in the panel provider is a debugging tax.

Environment discipline. Local with seeded demo content, staging with a sanitized copy, production with APP_DEBUG=false, php artisan filament:optimize, and no demo users. Because seeders are opinionated, make a ProductionSeeder that creates exactly one admin from env vars.

Gotchas and Tips

No upgrade path — pin and plan. This is the biggest cost. The kit is pinned to a Filament major version; a Filament 4 bump is a manual migration of every resource, not a composer update. Check the kit's composer.json against the Filament version you need before committing, and pin Filament explicitly so a transitive update doesn't break the panel.

Seeded credentials are real credentials. Default admin emails/passwords in seeders are the single most common way these kits get compromised. Change them, gate the demo seeder behind app()->environment('local'), and rotate any API keys shipped in .env.example.

Permissions cache. After changing roles/permissions in seeders, stale caches produce "the button is there but 403s" behavior:

php artisan permission:cache-reset   # or: cache:forget spatie.permission.cache
php artisan optimize:clear

Filament assets and Livewire. If the admin panel renders unstyled or components misbehave after a pull, it is almost always assets:

php artisan filament:assets
php artisan filament:upgrade   # if available in your version
php artisan optimize:clear

Theme/settings are cached. Changing a setting in the UI and seeing nothing change usually means a cached settings/config value or a view cache — clear caches before editing Blade files in frustration.

Media and image conversions. Uploads that appear in the panel but 404 on the front site = missing storage:link or a mismatched disk in config/filesystems.php. Conversions (thumbnails, OG images) are slow synchronously; move them to a queue and make sure a worker runs in every environment, or OG images will silently be the original full-size file.

Rich text is a trust boundary. Rendering {!! $model->body !!} is standard here, but sanitize on save if non-admin roles can author content, and strip scripts. The kit gives you the field; it does not give you the policy.

Front-end build is a separate deploy step. Blade components from the kit assume its Tailwind setup. If the front site looks unstyled in production but fine locally, npm run build did not run in CI.

Debugging checklist when something "isn't there": panel provider (is the resource registered / is the panel the right path?) → policy (canViewAny) → navigation group/hidden flags → resource shouldRegisterNavigation → permission cache. That order resolves most missing-resource reports in under five minutes.

Extension points to prefer: custom Filament pages and widgets (keeps kit resources untouched), custom Blade components/blocks for front-site sections, settings classes for anything an editor should change without a deploy, and a thin app/Support layer for shared content logic. Anything you can add beside kit files is upgrade insurance; anything you edit inside them is debt.