README

A clean and minimal Laravel starter template with Laravel Breeze authentication and RBAC-ready structure for building role-based applications quickly. Perfect for projects that need user authentication, role management, and separate dashboards right out of the box.

Features

✨ Laravel 12 - Latest Laravel framework
🔐 Laravel Breeze - Simple authentication scaffolding
👥 RBAC Structure - Role-based access control ready
🎨 Tailwind CSS - Modern utility-first CSS framework
🚀 Role-Based Dashboards - Separate dashboards for Super Admin, Admin, and users
📱 Responsive Design - Mobile-friendly layouts
🎯 Font Awesome Icons - Beautiful icons throughout
🎭 No-Role Page - Dedicated page for users without assigned roles
🧪 Pest Testing - Modern PHP testing framework

Requirements

PHP >= 8.2
Composer
Node.js & NPM
MySQL or any supported database

Installation

Creating a New Project from This Template

You can create a new project using Composer's create-project command:

composer create-project ianlabicani/laravel-blade-starter your-project-name

Manual Installation

Clone the repository:

git clone https://github.com/ianlabicani/laravel-blade-starter.git your-project-name
cd your-project-name

Run the setup script:

composer run setup

This will automatically:

Install PHP dependencies
Copy .env.example to .env
Generate application key
Run database migrations
Install NPM dependencies
Build frontend assets

Configure your .env file with your database credentials:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password

Run migrations to create database tables:

php artisan migrate

(Optional) Seed the database with sample data:

php artisan db:seed

Available Scripts

This template includes several useful Composer scripts to streamline your development workflow:

Setup Script

composer run setup

Sets up the entire project from scratch:

Installs all PHP dependencies
Creates .env file from example
Generates application key
Runs database migrations
Installs Node.js dependencies
Builds frontend assets

Development Script

composer run dev

Starts all development services concurrently:

Laravel development server (php artisan serve)
Queue worker (php artisan queue:listen)
Vite dev server (npm run dev)

This uses concurrently to run all three services in one terminal window with color-coded output.

Test Script

composer run test

Runs the test suite:

Clears configuration cache
Executes all Pest tests

Project Structure

Authentication Views

All authentication views are located in resources/views/auth/:

login.blade.php - User login
register.blade.php - User registration
forgot-password.blade.php - Password reset request
reset-password.blade.php - Password reset form
verify-email.blade.php - Email verification
confirm-password.blade.php - Password confirmation

Layout Templates

resources/views/public/layout.blade.php - Public pages layout
resources/views/admin/layout.blade.php - Admin dashboard layout
resources/views/super-admin/layout.blade.php - Super Admin dashboard layout

Role-Based Routing

routes/web.php - Public and dashboard routes
routes/auth.php - Authentication routes
routes/admin.php - Admin-only routes
routes/super-admin.php - Super Admin-only routes

Models

app/Models/User.php - User model with role relationships
app/Models/Role.php - Role model

Usage

Running the Application

Start the development server:

composer run dev

Or manually start services:

# Terminal 1: Laravel Server
php artisan serve

# Terminal 2: Queue Worker
php artisan queue:listen

# Terminal 3: Vite Dev Server
npm run dev

Visit http://localhost:8000 in your browser.

Role Management

Users can have roles assigned through the role_user pivot table. The dashboard automatically redirects users based on their role:

Super Admin → Super Admin Dashboard
Admin → Admin Dashboard
No Role → No-Role Page (informational page)

Customization

Update branding: Modify the app name in resources/views/public/layout.blade.php
Customize colors: Edit Tailwind classes throughout the views
Add new roles: Create migrations and update the Role model
Extend dashboards: Add new routes and views in respective role folders

Testing

Run the test suite:

composer run test

Or use Pest directly:

./vendor/bin/pest

AI-Assisted Development

This project includes comprehensive AI coding assistance to help you develop faster and more efficiently.

Copilot Instructions

Custom GitHub Copilot instructions are provided in .github/copilot-instructions.md to ensure AI suggestions follow the project's patterns and best practices. These instructions cover:

Project structure and architecture conventions
RBAC patterns and role management
Controller and view naming conventions
Route organization guidelines
Testing patterns with Pest
Tailwind CSS usage conventions

The instructions help AI assistants understand the project context and provide more accurate suggestions aligned with Laravel 12 and this starter's structure.

Laravel Boost MCP

For the best development experience, use Laravel Boost - a Model Context Protocol (MCP) server designed specifically for Laravel applications. Laravel Boost provides:

Smart Documentation Search - Version-specific Laravel documentation for your packages
Artisan Command Integration - Direct access to Artisan commands
Tinker Integration - Execute PHP code and query Eloquent models directly
Database Querying - Read from database without writing PHP
Browser Log Reading - Debug frontend issues easily
Absolute URL Generation - Get correct project URLs automatically

Installing Laravel Boost

php artisan boost:install

Once installed, Laravel Boost integrates with VS Code's GitHub Copilot and other AI assistants to provide context-aware development support.

Built With

Laravel 12 - PHP Framework
Laravel Breeze - Authentication Scaffolding
Tailwind CSS - CSS Framework
Font Awesome - Icon Library
Vite - Frontend Build Tool
Pest - Testing Framework

License

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Credits

Created by Ian Labicani

ianlabicani / laravel-blade-starter

Maintainers

Package info

Statistics

Security