README

Laravel Sail Starter Kit is an ultra-strict, type-safe Laravel skeleton engineered for developers who refuse to compromise on code quality. This opinionated starter kit enforces rigorous development standards through meticulous tooling configuration and architectural decisions that prioritize type safety, immutability, and fail-fast principles.

Why This Starter Kit?

Modern PHP has evolved into a mature, type-safe language, yet many Laravel projects still operate with loose conventions and optional typing. This starter kit changes that paradigm by enforcing:

100% Type Coverage: Every method, property, and parameter is explicitly typed
Zero Tolerance for Code Smells: Rector and PHPStan at maximum strictness catch issues before they become bugs
Immutable-First Architecture: Data structures favor immutability to prevent unexpected mutations
Fail-Fast Philosophy: Errors are caught at compile-time, not runtime
Automated Code Quality: Pre-configured tools ensure consistent, pristine code across your entire team
Just Better Laravel Defaults: Thanks to Essentials / strict models, auto eager loading, immutable dates, and more...

This isn't just another Laravel boilerplate—it's a statement that PHP applications can and should be built with the same rigor as strongly-typed languages like Rust or TypeScript.

Included Features

This Starter kit contains my starting point when developing a new Laravel project using Filament & Sail. Its based on the Laravel Starter Kit by Nuno Maduro, and includes the following features:

✅ Traefik as reverse proxy to serve your application locally and in production,
✅ Laravel Octane with FrankenPHP to supercharges your application's performance,
✅ Spatie Roles & Permission with Filament Shield,
✅ Updated for Laravel 12.*, Filament 4.1 and Livewire 3.6

Getting Started

Requires PHP 8.4+.

Create your type-safe Laravel application using Composer:

composer create-project shopperlabs/laravel-sail-starter-kit --prefer-dist example-app
# Or
laravel new example-app --using=shopperlabs/laravel-sail-starter-kit

Initial Setup

Navigate to your project and complete the setup:

cd example-app

# Setup project
composer dev:setup

# Start the development server
composer dev:run

Initialize the Application

Once your containers are running, initialize the application database and create your admin user:

./vendor/bin/sail artisan app:setup

This command will:

Run database migrations
Generate roles and permissions (via Filament Shield)
Create the storage symbolic link
Create an admin user with interactive prompts

You can also run it non-interactively by providing all options:

./vendor/bin/sail artisan app:setup \
  --admin-firstname="John" \
  --admin-lastname="Doe" \
  --admin-username="john.doe" \
  --admin-password="your-secure-password"

Configure Local Domain

Add your application domain (defined in APP_DOMAIN from .env) to your hosts file:

Linux/macOS:

sudo sh -c 'echo "127.0.0.1       your-domain.local" >> /etc/hosts'

Windows (as Administrator):

echo 127.0.0.1       your-domain.local >> C:\Windows\System32\drivers\etc\hosts

Replace your-domain.local with your actual APP_DOMAIN value.

MinIO Configuration (File Storage)

By default, the application uses MinIO for media file storage. After installation, you need to create the bucket and make it public.

Create and Make Bucket Public

Run this command via MinIO CLI container:

docker exec -it app-minio-1 sh
mc alias set local http://localhost:9000 sail password
mc anonymous set download local/universy
exit

Common Errors

"Disk named 'media' cannot be accessed": Bucket doesn't exist, run the configuration above.
403 Forbidden on image URLs: Bucket is not public, apply the public policy above.

Optional: Dokploy Deployment

If you're using Dokploy like me to deploy Docker-based apps, I've got you covered. Copy docker-compose.prod.yml.example to docker-compose.prod.yml and customize it—it's already configured with Dokploy's network setup.

cp docker-compose.prod.yml.example docker-compose.prod.yml

Optional: Browser Testing Setup

If you plan to use Pest's browser testing capabilities:

npm install playwright
npx playwright install

Verify Installation

Run the test suite to ensure everything is configured correctly:

composer test

You should see 100% test coverage and all quality checks passing.

Available Tooling

Development

composer dev:run - Starts Laravel sail, queue worker, log monitoring, and Vite dev server concurrently

Code Quality

composer lint - Runs Rector (refactoring), Pint (PHP formatting), and Prettier (JS/TS formatting)
composer test:lint - Dry-run mode for CI/CD pipelines

Testing

composer test:type-coverage - Ensures 100% type coverage with Pest
composer test:types - Runs PHPStan at level 10 (maximum strictness)
composer test:unit - Runs Pest tests with 100% code coverage requirement
composer test - Runs the complete test suite (type coverage, unit tests, linting, static analysis)

Maintenance

composer update:requirements - Updates all PHP and NPM dependencies to latest versions

License

Laravel Sail Starter Kit was created by Arthur Monney inspired by Laravel Starter Kit of Nuno Maduro under the MIT license.

shopperlabs / laravel-sail-starter-kit

Maintainers

Details