Laravel Sail Starter Kit Laravel Package

Getting Started

This is a starter kit/template, not a runtime library — "installing" means scaffolding a project, not composer require.

1. Create the project:

   laravel new my-app --using=shopperlabs/laravel-sail-starter-kit
   # or
   composer create-project shopperlabs/laravel-sail-starter-kit my-app
   

2. Bring up the containers and finish setup:

   cp .env.example .env
   ./vendor/bin/sail up -d
   sail composer install
   sail artisan key:generate
   sail artisan migrate --seed
   sail npm install && sail npm run dev
   

3. Log in at /admin with the seeded user from database/seeders/DatabaseSeeder.php (usually [email protected] / password — check the seeder, don't assume).

Look here first: app/Providers/Filament/AdminPanelProvider.php (panel config: path, middleware, colors, auth guard), app/Filament/ (your resources/pages/widgets), docker-compose.yml + compose.yaml for service definitions, and routes/web.php. First use case: generate a CRUD screen for an existing model — sail artisan make:filament-resource Post --generate — and you have a working admin in under a minute.

v1.2 pins Filament v5 and Livewire 4, so check composer.json before copying snippets from any v1.1.x-era tutorial.

Implementation Patterns

• Panel-first development. Everything admin-facing lives in a Filament panel provider. Add new areas (e.g. a separate Customer panel) by running sail artisan make:filament-panel Customer rather than hacking middleware.
• Resource generation loop. make:filament-resource --generate → tweak form()/table() → make:filament-relation-manager → make:filament-widget. Treat generated files as scaffolds; move shared form schemas into reusable schema classes once two resources overlap.
• Livewire 4 components for anything outside the panel (app/Livewire/, resources/views/livewire/). Prefer the single-file component style — it keeps markup and logic co-located and plays well with Alpine.
• Sail as the only entry point. Aliasing alias sail='./vendor/bin/sail' in your shell keeps commands short. Run tests with sail artisan test --parallel; the kit wires Pest/PHPUnit against the Sail MySQL container, so tests behave the same as CI.
• Keep an upstream remote to pull starter-kit changes into your project (see gotchas).
• Environment layering. Use .env for local Sail ports, and set APP_PORT/VITE_PORT/FORWARD_*_PORT rather than editing docker-compose.yml, so teammates with conflicting local ports can coexist.
• Deployment: build assets in CI (npm ci && npm run build), ship the compiled public/build, and never ship the Sail containers to production — swap DB_HOST/REDIS_HOST to managed services.

Gotchas and Tips

• No composer update path. Because this is a template, upstream fixes don't reach you automatically. Add git remote add upstream https://github.com/shopperlabs/laravel-sail-starter-kit.git early, then git fetch upstream && git diff HEAD upstream/main to review what changed before cherry-picking. Do this before your first major feature branch.
• v1.2 is a breaking jump for existing projects. Filament v4 → v5 and Livewire v3 → v4 both removed/renamed APIs (form/schema namespaces, action classes, Livewire directive syntax). Upgrading an existing app scaffolded from v1.1.x is not a dependency bump — budget for a migration or scaffold fresh and port your app/Filament code across.
• Re-publish after major upgrades. Filament ships config, views, and compiled assets. After upgrading, run sail artisan vendor:publish --tag=filament-config --force (review the diff first) and sail artisan filament:assets, otherwise you get stale Blade views or missing CSS.
• Debugbar 4 is a config-breaking bump. If you had a customized config/debugbar.php, re-publish and re-apply your changes. Confirm APP_DEBUG=false in production — Debugbar 4 will not silently no-op if it's enabled.
• Port collisions are the #1 first-run failure. Nginx on 80, MySQL on 3306, and Redis on 6379 commonly conflict with local installs. Change the *_PORT vars in .env, then sail down && sail up -d.
• Sail on Linux/WSL: run sail as your own user, not root, or you'll end up with root-owned files in storage/ and node_modules/. Fix with sail root-shell only when necessary, and sudo chown -R $USER . afterwards.
• Cache confusion after config edits: sail artisan optimize:clear is your first move when a panel route 404s or a color change doesn't appear.
• Node version drift: Vite + Prettier 3.8 need a modern Node LTS. Pin it with .nvmrc/engines so CI and Sail match.
• Extension points worth knowing: AdminPanelProvider (register plugins, render hooks, custom theme), app/Providers/AppServiceProvider.php (global model configs, Model::unguard()), and docker/ (custom PHP extensions, Xdebug toggles via SAIL_XDEBUG_MODE).