Installer Laravel Package

Getting Started

lara-zeus/filament-installer is a scaffolding tool rather than a runtime dependency: you use it once at the start of a project to get a Laravel app with Filament already wired up, then you spend the rest of your time in Filament itself. Treat it the way you treat laravel/laravel — it defines your starting point, not your day-to-day API surface.

Minimal steps:

1. Read the README on the repo first. The 1.0.1 release is explicitly a docs refresh, so the README is the authoritative source for the exact command and its flags — the command name and prompts are the most likely thing to drift between versions, so don't copy a command out of a blog post.
2. Pin the version. Because this is a one-shot skeleton, 1.0.x should be recorded in your onboarding notes (or a composer.json create-project reference) so a rebuild in six months produces the same baseline.
3. Run the installer into a clean directory, then immediately commit the generated result as your first commit. That commit is your real reference point — not the installer version.
4. Confirm the generated app boots: php artisan about, then hit the Filament panel path in a browser. If the panel loads and you can log in, the installer did its job and you can stop thinking about it.

First use case: standing up a new internal admin/tooling app. Run the installer, get a panel, add your first Resource with php artisan make:filament-resource, and ship. The value is the hour of Filament panel-provider wiring, auth setup, and asset publishing you don't do by hand.

Implementation Patterns

One-shot scaffold, then own it. The installer's output is yours. Don't build workflows that depend on re-running the installer; build them on the generated app. If you need to regenerate, do it in a scratch directory and diff against your repo to see what conventions changed.

Version-gated adoption. 1.0.1 adds Laravel 13 support. In practice that means: new projects can start on Laravel 13, but existing projects scaffolded on an earlier Laravel should not assume the installer's structure is compatible. Check the composer.json constraints the installer writes (php, laravel/framework, filament/filament) before deciding whether an existing app can follow along — the framework upgrade is a separate, riskier exercise.

House-standard template. If your team spins up several Filament apps, the highest-leverage pattern is: run the installer once, apply your house conventions (pint config, CI workflow, .env.example, base panel provider, standard roles/permissions setup), commit that as an internal template repo. The installer becomes a bootstrap input, not an ongoing dependency.

Pair it with Filament's own generators. Day-to-day work after install is make:filament-resource, make:filament-page, make:filament-widget, panel provider edits in app/Providers/Filament/. Everything the installer did is now just files you edit normally — no abstraction layer to learn.

Containerised setup. Since the installer produces a full Laravel app, the usual Sail/Docker/local-dev patterns apply unchanged. If you script project creation (e.g. a make new-project target), that's where a pinned installer version belongs.

CI integration. Once scaffolded, CI is just Laravel CI. The one addition worth making: assert in CI that the panel route responds (a smoke test hitting the login page), because that's the single thing the installer is responsible for and the easiest thing to silently break during a refactor.

Gotchas and Tips

• The installer is not upgradeable in place. composer update on a project you created from it will not restructure your app. Skeleton/starter packages are snapshots. Plan for manual diffs when the baseline changes — and expect the 1.0.x line to keep changing, since 1.0.1 already touched docs and framework support.
• Laravel 13 support is new. This is the only substantive change in 1.0.1 (Update docs and laravel 13). Treat it as "supported, lightly exercised" rather than battle-tested. Pin PHP and framework versions in the generated app, and run the test suite plus a manual panel smoke test rather than assuming parity with the Laravel 12 path.
• Idempotency. Installers that write .env, publish assets, or append to providers are rarely safe to run twice on the same directory. Always scaffold into an empty path. If the tool offers an --force/overwrite flag, assume it means "clobber" and keep your work committed first.
• Don't commit secrets from the generated .env. Verify .gitignore covers it immediately after scaffolding, before your first commit — this is the most expensive mistake available in this workflow.
• Missing assets after a fresh clone. If the panel renders unstyled or JS is dead, it's almost always unpublished/missing Filament assets or a missing frontend build step, not an installer bug. Check the published asset directories and run the documented install/build commands from the README.
• Config caching confuses panel changes. After editing a Filament panel provider or config, php artisan config:clear and php artisan optimize:clear before concluding something is broken. In production, remember config:cache will freeze the values you set locally.
• Debugging the installer itself. Run commands with -v to see what it's actually doing. If it fails midway you'll be left with a half-written directory — delete and start clean rather than patching by hand; a partial scaffold is worse than none.
• Extension points are just files. There's no plugin API here worth learning: customise by editing the generated providers/config, or fork the template entirely if you need different defaults. Do not wrap the installer in your own tooling unless you're prepared to track its releases.
• Verify before you build a training doc on it. 1.0.1 includes a first-time contributor typo fix, which suggests the package is early and moving. Confirm the exact command, prompts, and generated directory names against the current README on the day you write internal docs, and prefer linking to the repo over transcribing commands.