README

A modern, production-ready Laravel starter kit featuring Livewire 4 and Mary UI. Build beautiful web applications with a complete authentication system, user management, and developer-friendly tooling.

✨ Features

🎨 Frontend Stack

Livewire 4.x for reactive components with improved performance
Mary UI 2.x - Beautiful, accessible UI components
Tailwind CSS 4.x + DaisyUI v5 for styling
Blade Heroicons and Font Awesome 7 icons integration
Vite 8 for lightning-fast asset bundling
Live version badges on the welcome page, read from the running app and composer.lock

🔐 Authentication & User Management

Complete authentication system (login, registration, password reset)
Email verification with resend functionality
Password confirmation for sensitive operations
User profile management with avatar uploads
User management dashboard with full CRUD operations
User status management (Active, Inactive, Suspended)
Advanced filtering and search capabilities
Avatar management with automatic cleanup
Google OAuth integration for social login
Roles & Permissions system powered by Spatie Laravel Permission
Role-based access control with granular permission management
User role assignment and permission checking middleware

🔗 OAuth Socialite Integration

Laravel Socialite integration with extensible provider system
Google OAuth authentication out of the box
Social account linking to existing user accounts
Automatic user creation for new social logins
Extensible architecture for adding new OAuth providers
Secure token handling and user data synchronization

🎭 Demo Mode

Scheduled data reset on any cron expression, or hourly/daily/weekly/monthly
Rotating published password for the admin account, filled into the login form
The published account cannot be edited, so one visitor cannot lock out the next
Super-admin cannot sign in and gets no gate bypass
demo:doctor audits the configuration and exits non-zero on anything that would destroy data or publish a secret
Visual indicator that counts down from the schedule the scheduler actually runs
Per-visitor isolation on the Users screen — each visitor sees the seeded accounts plus the ones they made, and a button that clears only their own

🏗️ Architecture & Developer Experience

Laravel 13.x with PHP 8.4+ support
SQLite database by default (easy local setup)
Pest 5 testing framework with 230+ comprehensive tests, running in parallel
Code quality tools: Pint (formatting), Rector (refactoring)
Debugging tools: LaraDumps, Laravel Pail
Development workflow with Concurrently for multi-process dev server
OAuth Socialite Integration with extensible architecture for new oauth providers

🧪 Testing Coverage

Complete test coverage for authentication flows
User management CRUD operations testing
Roles and Permissions management CRUD operations testing
Demo mode functionality testing
File upload and avatar management testing
Form validation and error handling
Database cleanup and file storage testing

📁 File Management

Avatar upload with cropping support (Cropper.js)
Automatic file cleanup on user deletion
File validation (type, size)
Storage testing with fake disks

🚀 Quick Start

Prerequisites

PHP 8.4+ (Laravel 13 needs 8.3+, Pest 5 raises the floor to 8.4)
Node.js 22+
Composer
SQLite (included with PHP)

Installation

# Install via Laravel Installer
laravel new my-app --using=lauroguedes/mary-ui-starter-kit

# or Composer
composer create-project lauroguedes/mary-ui-starter-kit my-app

# (Optional) Generate fake data for testing
php artisan db:seed

# Default user
user: test@user.com
pw: secret

Clone the repository manually:

# Clone the repository
git clone https://github.com/lauroguedes/mary-ui-starter-kit
cd mary-ui-starter-kit

# Install PHP dependencies
composer install

# Copy environment file and generate app key
cp .env.example .env
php artisan key:generate

# Set up the database
php artisan migrate --seed

# Install frontend dependencies
npm install
# or if you use Yarn
yarn

# Run the development server
php artisan serve
# In a separate terminal
npm run dev
# or
yarn dev

Development Workflow

For an enhanced development experience with hot reloading:

# Start all development services (server, queue, logs, vite)
composer dev

Visit http://localhost:8000 to view your application.

This runs:

Laravel development server
Queue worker
Log monitoring (Pail)
Vite dev server with hot reload

🧪 Testing

The suite runs on Pest 5 and is parallel-safe, which takes a full run from ~40s down to ~9s.

# Run the whole suite in parallel (the default)
composer test

# Rerun only what recent changes touched (Test Impact Analysis)
composer test:tia

# Enforce the 80% coverage gate
composer test:coverage

# Refresh the time-balanced shard timings after adding or removing tests
composer test:shards

Or call Pest directly:

./vendor/bin/pest --parallel
./vendor/bin/pest --shard=1/2 --parallel

Notes on the Pest 5 features

Parallel is the default. Anything that writes to shared state outside the database must stay process-local — that is why phpunit.xml sets APP_MAINTENANCE_DRIVER=array, so demo:reset calling artisan down cannot put other test processes into maintenance mode.
Tia (--tia) needs a coverage driver (pcov or Xdebug). Without one Pest prints a notice and runs the full suite instead.
Time-balanced sharding reads tests/.pest/shards.json, which is committed so CI shards stay stable. CI runs two shards per PHP version.

🔧 Customization

Key environment variables for customization:

# Appearance settings
APP_LAYOUT=sidebar      # Options: sidebar, header
LOGIN_LAYOUT=card       # Options: card, simple, split

# Demo mode settings — see config/demo.php for every key, documented inline
DEMO_MODE=false             # Turn this installation into a public demonstration
DEMO_RESET_SCHEDULE=hourly  # A cron expression, or hourly/daily/weekly/monthly
DEMO_EMAIL=admin@user.com   # The account whose password is published and rotated
DEMO_CREDENTIALS_STORE=file # Where that password is kept: file, cache or null
DEMO_SANDBOX=scoped         # shared | scoped — see "Per-visitor isolation" below

Warning

DEMO_MODE=true allows demo:reset to drop the database. Run php artisan demo:doctor before the first scheduled reset, and never turn it on for an installation holding anything you want to keep.

Per-visitor isolation

With DEMO_SANDBOX=scoped, each visitor gets the fifty-three seeded accounts plus whatever they create. The Users screen is a list everybody adds to, which is the one case where a shared demo falls apart — the first visitor's test accounts are the second visitor's clutter — so App\Models\User carries the package's BelongsToSandbox trait and a nullable demo_sandbox_id column.

The identifier lives in the session. Rows the seeder made carry none, so they belong to everybody, which is what keeps the demo populated. The bar's reset button then reads Clear what you created and deletes only that visitor's rows; the scheduled reset still rebuilds the whole thing.

Roles and permissions stay shared on purpose: they are part of what the kit demonstrates, not something a visitor should fork. Two other things follow from sandboxing the authentication model — unique:users,email is query-builder validation and sees every sandbox, so two visitors cannot register the same address, and logging out does not end a sandbox (the reset button is how a visitor gets a clean slate).

Set DEMO_SANDBOX=shared to turn all of it off; the trait and the column then do nothing at all. demo:doctor warns if the models stay marked while the driver does not agree.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Run the test suite: composer test
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Code Quality

We maintain high code quality standards:

# Format code
./vendor/bin/pint

# Refactor code
./vendor/bin/rector

# Run tests
composer test

📋 Roadmap

Role-based permissions system ✅
Demo mode for showcasing ✅
Advanced Log and Audit
Multi-tenant support
Advanced notification system
Dashboard analytics
API integration with Laravel Sanctum

🆘 Support

Documentation: Mary UI Docs
Issues: GitHub Issues

📝 License

This project is open-sourced software licensed under the MIT license.

Built with ❤️ by Lauro Guedes

⭐ Star this repository if it helped you!

lauroguedes / mary-ui-starter-kit

Package info

Security

Statistics