Laravel Starter Kit

A type-safe, strict Laravel 12 starter kit with comprehensive guidelines and modern tooling.

Requirements

Nix + Laravel Sail is the only supported setup.

Setup

First, create .envrc from the example:

cp .envrc.example .envrc

Then load the Nix environment:

direnv allow                    # Auto-load environment (requires direnv installed)
# or
nix flake update && nix develop

This provides:

• PHP 8.4 with Redis extension
• Composer
• Bun (JavaScript runtime)
• Docker & Docker Compose (for Laravel Sail)
• Playwright (for browser testing)

Services (via Laravel Sail)

All services run in Docker containers:

• nginx - Web server with SSL
• PostgreSQL 18 - Database
• Valkey (Redis) - Cache & queue
• Mailpit - Email testing
• Rustfs - File storage

Quick Start

# 1. Install dependencies
install-deps

# 2. Setup environment
cp .env.example .env
artisan key:generate

# 3. Start development server
dev

# 4. Run database migrations
artisan migrate

The composer dev command automatically manages all Docker containers and starts your development environment.

Available Services

Once running, access services at:

• Web: http://localhost:80 (HTTP) / https://localhost:443 (HTTPS)
• Vite: http://localhost:5173 (Frontend dev server)
• Database: localhost:5432 (PostgreSQL)
• Cache: localhost:6379 (Valkey/Redis)
• Email: http://localhost:8025 (Mailpit dashboard)
• File Storage: http://localhost:9001 (Rustfs console)

Documentation

• LARAVEL_GUIDELINES.md - Complete development guidelines and standards

Common Commands

# Primary - Start development environment (recommended)
composer dev                    # Start all services + dev server
dev                             # Nix alias for composer dev

# Code Quality
composer lint                   # Fix all code quality issues
composer test                   # Run full test suite
composer test:types             # PHPStan type checking
composer test:type-coverage     # Verify 100% type coverage

Nix Commands Reference

These commands are available when using Nix (nix develop or direnv allow). Use composer dev as your primary development command:

dev                             # Alias for composer dev
sail                            # Laravel Sail shortcut (for advanced usage)
run-test                        # Run tests in Sail
install-deps                    # Install PHP, Bun, Playwright
update-deps                     # Update dependencies
lint                            # Run code linting
test-lint                       # Dry-run lint check
artisan <cmd>                   # Run artisan command
generate-types                  # Generate TypeScript types
composer                        # Run composer
php                             # Run PHP

License

MIT