README

LaravelStark is an opinionated starter kit for Laravel with Filament that enforces rigorous development standards through meticulous tooling configuration and architectural decisions that prioritize type safety, immutability, and fail-fast principles.

✨ Features

✅ 100% Type Coverage with Pest
✅ PHPStan Level 9 (maximum strictness)
✅ Filament 4.1 admin panel pre-configured
✅ Log Viewer (opcodesio/log-viewer)
✅ Rector, Pint, Prettier for automated code quality
✅ GitHub Actions CI/CD workflows
✅ Strict Models and immutable dates
✅ SQLite default (production-ready MySQL/PostgreSQL support)

📋 Prerequisites

Before installing LaravelStark, ensure you have:

PHP 8.4+ with extensions: mbstring, xml, curl, pdo, sqlite3, pdo_sqlite
Composer 2.7+
Node.js 20+ and npm
Laravel Installer (recommended)
Database: SQLite (default), MySQL 8.0+, or PostgreSQL 15+

Installing Laravel Installer

If you haven't installed the Laravel Installer yet:

composer global require laravel/installer

Make sure Composer's global bin directory is in your PATH.

🚀 Installation

Quick Start with Laravel Installer

You can use the Laravel Installer to install this starter kit.

laravel new my-app --using=dsolodev/laravelstark
cd my-app

Alternative: Using Composer

composer create-project dsolodev/laravelstark my-app
cd my-app

1. Install Dependencies

npm install
npm run build

2. Environment Setup

The .env file is automatically created during installation. Generate your application key:

php artisan key:generate

Review and update .env settings as needed:

APP_NAME=LaravelStark
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost

# Configure developer email for log viewer access
DEVELOPER_EMAIL=jc@dsolo.dev

# Database (SQLite by default)
DB_CONNECTION=sqlite

3. Database Setup

The SQLite database is created automatically during installation. Run migrations and seeders:

php artisan migrate --seed

Default Developer Credentials:

Email: jc@dsolo.dev
Password: password

⚠️ Change these credentials immediately in production!

4. Start Development

composer dev

This command starts multiple services concurrently:

Laravel server at http://localhost:8000
Queue worker for background jobs
Log monitoring with Pail
Vite dev server for hot module replacement

Access Points:

Admin Panel: http://localhost:8000/admin
Log Viewer: http://localhost:8000/log-viewer

6. Verify Installation

Run the test suite to ensure everything is configured correctly:

composer test

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

🔧 Configuration

Admin Panel Access

The Filament admin panel is located at the root path (/) by default. To change this:

// app/Providers/Filament/AdminPanelProvider.php

public function panel(Panel $panel): Panel
{
    return $panel
        ->path('admin')  // Change from '' to 'admin'
        // ... rest of configuration
}

Log Viewer Authentication

By default, only users with the developer email can access logs. Configure in .env:

DEVELOPER_EMAIL=jc@dsolo.dev

Or modify the authentication logic:

// app/Providers/AppServiceProvider.php

LogViewer::auth(
    fn(Request $request): bool => $request->user()?->email === config('app.developer_email')
);

Database Configuration

For MySQL:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravelstark
DB_USERNAME=root
DB_PASSWORD=

For PostgreSQL:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=laravelstark
DB_USERNAME=postgres
DB_PASSWORD=

🧪 Testing

Run Complete Test Suite

composer test

This executes:

✅ Pint code style check (dry-run)
✅ Rector refactoring check (dry-run)
✅ Prettier formatting check
✅ PHPStan static analysis (level max)

Individual Test Commands

# Static analysis with PHPStan
composer test:types

# Type coverage check
composer test:type-coverage

# Code style check (dry-run)
composer test:lint

# Refactoring check (dry-run)
composer test:refactor

Fix Code Style Issues

composer lint

This automatically fixes:

PHP code style with Pint
PHP refactoring with Rector
JavaScript/CSS formatting with Prettier

📁 Project Structure

app/
├── Actions/              # Business logic actions (single-purpose classes)
├── Enums/                # Type-safe enumerations
├── Filament/             # Filament admin panel
│   ├── Resources/        # CRUD resources
│   ├── Pages/            # Custom pages
│   └── Widgets/          # Dashboard widgets
├── Http/
│   └── Controllers/      # HTTP controllers
├── Models/               # Eloquent models
└── Providers/            # Service providers

database/
├── factories/            # Model factories
├── migrations/           # Database migrations
└── seeders/              # Database seeders

tests/
├── Feature/              # Integration/feature tests
└── Unit/                 # Unit tests

resources/
├── css/                  # Tailwind CSS
├── js/                   # JavaScript
└── views/                # Blade templates

Architecture Patterns

Actions Pattern

Encapsulate business logic in single-purpose action classes:

// app/Actions/Users/CreateUserAction.php

final readonly class CreateUserAction
{
    public function handle(array $data): User
    {
        return DB::transaction(function () use ($data) {
            $user = User::create($data);
            // Additional business logic...
            return $user;
        });
    }
}

Type-Safe Enums

Use enums for constants and status values:

// app/Enums/UserRole.php

enum UserRole: string
{
    case ADMIN = 'admin';
    case USER = 'user';
    case GUEST = 'guest';
}

🛠️ Development Tools

Available Commands

# Start all development services
composer dev

# Code quality
composer lint                    # Auto-fix code style issues
composer test:lint              # Check code style (dry-run)

# Testing
composer test                   # Run full test suite
composer test:types             # Run PHPStan analysis
composer test:type-coverage     # Check type coverage

# Maintenance
composer update:requirements    # Update all dependencies

Pre-configured Tools

Pint - Code style fixer (PSR-12 + Laravel)
Rector - Automated refactoring
PHPStan - Static analysis (level 9)
Pest - Testing framework
Peck - Spell checker
Prettier - JS/CSS formatter
Larastan - PHPStan for Laravel

🔍 Troubleshooting

FontAwesome Icons Not Displaying

Problem: Icons show as squares or don't load.

Solutions:

Verify .npmrc exists with correct token:

cat .npmrc

Clear npm cache and reinstall:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Rebuild assets:

npm run build

Clear browser cache or use incognito mode

Tests Failing

Problem: Tests fail after fresh installation.

Solutions:

Clear Laravel caches:

php artisan config:clear
php artisan cache:clear
php artisan view:clear

Regenerate autoload files:

composer dump-autoload

Verify database:

php artisan migrate:fresh --seed

Check PHP version:

php -v  # Should be 8.4+

Type Coverage Issues

Problem: Type coverage below 100%.

Solution:

Run type coverage check:

composer test:type-coverage

Add missing type hints to flagged methods/properties
Example fixes:

// ❌ Before
public function handle($data)
{
    return $this->service->process($data);
}

// ✅ After
public function handle(array $data): ProcessResult
{
    return $this->service->process($data);
}

Database Issues

SQLite Issues:

# Recreate database
rm database/database.sqlite
touch database/database.sqlite
php artisan migrate:fresh --seed

MySQL Connection Failed:

Verify MySQL is running:

mysql --version
sudo systemctl status mysql  # Linux
brew services list           # macOS

Check credentials in .env
Create database:

mysql -u root -p -e "CREATE DATABASE laravelstark;"

Vite Build Errors

Problem: npm run build fails.

Solutions:

Update Node.js to version 20+:

node -v

Clear Vite cache:

rm -rf node_modules/.vite

Check for port conflicts (default: 5173)

CI/CD Failures

Problem: GitHub Actions failing.

Solutions:

Ensure FONTAWESOME_PACKAGE_TOKEN secret is set in GitHub repo:
- Go to Settings → Secrets → Actions
- Add new secret: FONTAWESOME_PACKAGE_TOKEN
Verify workflows in .github/workflows/
Check PHP version compatibility in workflows

🔐 Security

Production Deployment Checklist

Before deploying to production:

Change default credentials (admin@example.com / password)
Update ADMIN_EMAIL in .env to your admin email
Set APP_DEBUG=false in production
Use strong APP_KEY (auto-generated, keep secure)
Configure proper database (MySQL/PostgreSQL, not SQLite for high-traffic)
Set up mail driver (not log driver)
Enable HTTPS (APP_URL=https://yourdomain.com)
Review file permissions (755 for directories, 644 for files)
Set up queue worker (Supervisor or similar)
Configure backups (database, storage, .env)
Never commit .env or .npmrc files
Set up monitoring (Laravel Telescope, Sentry, etc.)
Configure CORS if using API
Set secure session cookie (SESSION_SECURE_COOKIE=true)

Environment Security

Sensitive Files (Never Commit):

.env - Environment variables
.npmrc - FontAwesome Pro token
storage/*.key - Encryption keys
auth.json - Composer authentication

These are already in .gitignore.

User Permissions

By default, only authenticated users with is_active = true can access the admin panel. Modify authorization:

// app/Models/User.php

public function canAccessPanel(Panel $panel): bool
{
    // Add custom logic
    return $this->is_active && $this->hasRole('admin');
}

Code Standards

Use strict types: declare(strict_types = 1);
Add type hints on all methods and properties
Follow PSR-12 coding standards
Maintain 100% test coverage
Write descriptive commit messages
Run composer test before committing

For detailed guidelines, see CONTRIBUTING.md.

📖 Resources

Official Documentation

Packages Used

laravel/framework - The Laravel Framework
filament/filament - Admin panel
opcodesio/log-viewer - Log viewer
larastan/larastan - PHPStan for Laravel
pestphp/pest - Testing framework
rectorphp/rector - Automated refactoring

📝 License

LaravelStark is open-sourced software licensed under the MIT license.

👤 Author

Created by: dsolodev
GitHub: @dsolodev
Repository: dsolodev/laravelstark

⭐ If you find this starter kit helpful, please consider giving it a star on GitHub!

For questions or issues, please open an issue or start a discussion.

dsolodev / laravelstark

Maintainers

Details

README

✨ Features

📋 Prerequisites

Installing Laravel Installer

🚀 Installation

Quick Start with Laravel Installer

Alternative: Using Composer

1. Install Dependencies

2. Environment Setup

3. Database Setup

4. Start Development

6. Verify Installation

🔧 Configuration

Admin Panel Access

Log Viewer Authentication

Database Configuration

🧪 Testing

Run Complete Test Suite

Individual Test Commands

Fix Code Style Issues

📁 Project Structure

Architecture Patterns

🛠️ Development Tools

Available Commands

Pre-configured Tools

🔍 Troubleshooting

FontAwesome Icons Not Displaying

Tests Failing

Type Coverage Issues

Database Issues

Vite Build Errors

CI/CD Failures

🔐 Security

Production Deployment Checklist

Environment Security

User Permissions

Code Standards

📖 Resources

Official Documentation

Packages Used

📝 License

👤 Author