Laravel React Starter Kit 🚀

A modern fullstack starter kit prepared for Docker-based development. Provides fast and consistent development environment by running Laravel and React technologies inside Docker containers.

✨ Features

• 🐳 Docker-Based Development - Consistent development environment
• Laravel 12 - Backend API and web framework
• React 19 - Modern frontend library
• Inertia.js - Laravel-React bridge for SPA-like experience
• TypeScript - Type-safe development
• Tailwind CSS - Utility-first CSS framework
• Radix UI - Accessible UI components
• Vite - Fast build tool
• MySQL & Redis - Database and caching
• ESLint & Prettier - Code quality and formatting
• Dark/Light Mode - Theme support
• Hot Reload - Instant development feedback

📋 Requirements

Only these two tools are needed:

• Docker (20.10+)
• Docker Compose (2.0+)

💡 Note: You don't need to install tools like PHP, Node.js, Composer on your local machine! Everything runs inside Docker containers.

🚀 Quick Start

1️⃣ Clone the Repository

git clone https://github.com/muammertopcu/laravel-react-devkit
cd laravel-react-devkit

2️⃣ Start with One Command

# Automatic installation and startup
./setup.sh

🎉 That's it! The application is ready:

• Backend: http://localhost
• Frontend Dev Server: http://localhost:5173
• phpMyAdmin: http://localhost:8080 (Database management)
• Database: MySQL (localhost:3306) - For app connection only
• Redis: localhost:6379 - For app connection only

3️⃣ Development Workflow

# Start containers
docker-compose up -d

# Frontend development server (with hot reload)
docker-compose exec app npm run dev

# Backend development server
docker-compose exec app php artisan serve --host=0.0.0.0

# Watch code changes in new terminal
docker-compose logs -f app

🐳 Docker Development

Managing Containers

# Start all services
docker-compose up -d

# Start specific service
docker-compose up -d app

# Stop containers
docker-compose down

# Rebuild containers
docker-compose up -d --build

# View container logs
docker-compose logs -f app

Development Commands

# Open bash inside container
docker-compose exec app bash

# Composer commands
docker-compose exec app composer install
docker-compose exec app composer require package-name

# NPM commands
docker-compose exec app npm install
docker-compose exec app npm run dev
docker-compose exec app npm run build

# Laravel Artisan commands
docker-compose exec app php artisan migrate
docker-compose exec app php artisan make:controller ControllerName
docker-compose exec app php artisan queue:work

# Database operations
docker-compose exec app php artisan migrate:fresh --seed
docker-compose exec db mysql -u root -p laravel_db

Useful Docker Tips

# Clean all containers
docker-compose down -v
docker system prune -a

# For frontend hot reload
docker-compose exec app npm run dev -- --host 0.0.0.0

📁 Project Structure

├── app/                    # Laravel application code
│   ├── Http/Controllers/   # API and web controllers
│   ├── Models/            # Eloquent models
│   └── Providers/         # Service providers
├── resources/
│   ├── js/                # React components and TypeScript code
│   │   ├── components/    # Reusable components
│   │   ├── pages/         # Inertia pages
│   │   ├── layouts/       # Page layouts
│   │   ├── hooks/         # Custom React hooks
│   │   └── types/         # TypeScript type definitions
│   ├── css/               # Tailwind CSS and style files
│   └── views/             # Blade templates
├── routes/                # Route definitions
├── database/              # Migrations and seeders
├── tests/                 # Unit and feature tests
└── docker/                # Docker configuration files

🔧 Development Workflow

Daily Development

# 1. Start the project
docker-compose up -d

# 2. Start frontend development server (hot reload)
docker-compose exec app npm run dev

# 3. Watch backend in separate terminal
docker-compose logs -f app

# 4. Code quality check
docker-compose exec app npm run lint
docker-compose exec app ./vendor/bin/pint

# 5. Run tests
docker-compose exec app php artisan test

New Feature Development

# Create migration
docker-compose exec app php artisan make:migration create_posts_table

# Create model
docker-compose exec app php artisan make:model Post

# Create controller
docker-compose exec app php artisan make:controller PostController

# Create React component (manually)
# resources/js/components/Post.tsx

# Run migration
docker-compose exec app php artisan migrate

# Test frontend build
docker-compose exec app npm run build

Database Operations

# Run migrations
docker-compose exec app php artisan migrate

# Reset database and seed
docker-compose exec app php artisan migrate:fresh --seed

# Connect to MySQL shell
docker-compose exec db mysql -u laravel -p laravel_db

# Use phpMyAdmin (Web interface)
# http://localhost:8080
# Username: laravel
# Password: laravel

# Database backup
docker-compose exec db mysqldump -u laravel -p laravel_db > backup.sql

Database/Redis Access Tools

Web-Based:

• phpMyAdmin: http://localhost:8080 (MySQL management)

Terminal/CLI-Based:

# MySQL CLI
docker-compose exec db mysql -u laravel -p

# Redis CLI
docker-compose exec redis redis-cli

# Laravel Tinker (for Eloquent testing)
docker-compose exec app php artisan tinker

Desktop Clients (Optional):

• MySQL: TablePlus, Sequel Pro, MySQL Workbench
• Redis: RedisInsight, Medis
• Connection: localhost:3306 (MySQL), localhost:6379 (Redis)

🎨 UI Components

The project includes modern and accessible UI components using Radix UI and Tailwind CSS:

• Avatar
• Button
• Checkbox
• Dialog
• Dropdown Menu
• Navigation Menu
• Select
• Tooltip
• Toggle
• and more...

🌙 Theme System

The project comes with automatic dark/light mode support. The theme system stores user preferences using localStorage and follows the system theme.

🔄 Inertia.js

This project uses Inertia.js to provide a seamless connection between Laravel backend and React frontend. This enables:

• SPA-like user experience
• Server-side routing
• Shared data management
• Automatic CSRF protection

🚀 Production Deployment

Docker Production Build

# Build production image
docker build -t laravel-react-app .

# Run production container
docker run -d -p 80:80 laravel-react-app

# Production with Docker Compose
docker-compose -f docker-compose.prod.yml up -d

Manual Production Setup

If you want to deploy without using Docker:

# Production dependencies
composer install --optimize-autoloader --no-dev

# Frontend production build
npm run build

# Laravel optimizations
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Permissions
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

🧪 Testing

# Laravel unit/feature tests
docker-compose exec app php artisan test

# Specific test file
docker-compose exec app php artisan test tests/Feature/DashboardTest.php

# Test with coverage
docker-compose exec app php artisan test --coverage

# Frontend tests (if you add them)
docker-compose exec app npm run test

# Browser container for E2E tests
docker-compose -f docker-compose.test.yml up -d

📝 API Documentation

For API endpoints and usage examples, you can examine the files in the /routes folder:

• web.php - Web routes
• auth.php - Authentication routes
• settings.php - Settings routes

🤝 Contributing

1. Fork this repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push your branch (git push origin feature/amazing-feature)
5. Create a Pull Request

🔧 Troubleshooting

Docker-Related Issues

Container won't start:

# Check container status
docker-compose ps

# View detailed logs
docker-compose logs app

# Rebuild container
docker-compose down
docker-compose up -d --build

Port conflicts:

# Check ports in use
lsof -i :8000
lsof -i :3000

# Change ports in docker-compose.yml
ports:
  - "8001:8000"  # Use 8001 instead of 8000

Database connection issues:

# Make sure MySQL container is running
docker-compose ps db

# Test database container connection
docker-compose exec app php artisan tinker
# >>> DB::connection()->getPdo();

# Connect directly to MySQL (terminal)
docker-compose exec db mysql -u laravel -p

# Use phpMyAdmin for web interface
# http://localhost:8080

Can't access MySQL/Redis ports from browser:

💡 Note: MySQL (3306) and Redis (6379) ports are database connection ports, not web interfaces!

• For database management: http://localhost:8080 (phpMyAdmin)
• MySQL connection: Only from within the application or database clients
• Redis connection: Only from within the application or Redis clients

Frontend hot reload not working:

# Run Vite dev server with correct settings
docker-compose exec app npm run dev -- --host 0.0.0.0 --port 3000

# Use localhost:3000 in browser

Performance Optimizations

# Use bind mounts instead of Docker volumes (for development)
# Keep Composer cache on host
volumes:
  - ~/.composer:/tmp/composer

# Mount node modules as volume
volumes:
  - node_modules:/var/www/node_modules

Common Errors

1. Memory error: Increase memory limit in Docker Desktop (4GB+)
2. Permission error: Set user IDs inside container
3. Hot reload not working: Check host setting in Vite config

Log Files

# All container logs
docker-compose logs -f

# Specific container logs
docker-compose logs -f app

# Laravel application logs
docker-compose exec app tail -f storage/logs/laravel.log

# Nginx logs (if using)
docker-compose logs -f nginx

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙏 Acknowledgments

This project uses the following open source projects:

• Laravel
• React
• Inertia.js
• Tailwind CSS
• Radix UI
• Vite

---

🎯 Using as Starter Kit

This project is designed as a template for your new Laravel + React projects:

1. Fork/Clone

git clone <this-repo-url> new-project-name
cd new-project-name
rm -rf .git
git init

2. Customize the Project

# Change project name in composer.json
# Update project information in package.json
# Edit .env.example according to your project

3. Quick Start

./setup.sh

4. Make Your First Commit

git add .
git commit -m "Initial commit from Laravel React Starter Kit"
git remote add origin <new-repo-url>
git push -u origin main

💡 Tip: During development, you only need to use docker-compose up -d and docker-compose exec app npm run dev commands!

---