Download the PHP package yanpenalva/starter-kit-laravue without Composer

🚀 LaraVue Starter Kit

The LaraVue Starter Kit is a full-stack boilerplate combining Laravel 13 and Vue 3 + Quasar Framework, built for scalable, testable, and maintainable web applications. It provides a pre-configured environment for authentication, user and permission management, dashboards, REST APIs, automated testing, and development observability.

📑 Table of Contents

1. Architecture Overview
2. Installation
3. Husky (Git Hooks)
4. Database Configuration
5. Fix Access Permissions (Spatie Permission Cache)
6. Key Features
7. Technology Stack
8. Queues and Horizon Monitoring
9. Project Architecture
10. Docker Services
11. Testing
12. Best Practices
13. Commit Conventions
14. Code Standards

⚙️ Architecture Overview

This starter kit runs entirely in Docker (Alpine) containers for consistent local and CI environments. It includes containers for the app, Nginx, PostgreSQL, Redis, and Mailpit, ensuring isolated and reproducible development.

📥 Installation

1️⃣ Clone the repository

2️⃣ Environment setup

3️⃣ Build and start containers

Verify your database settings:

4️⃣ Install dependencies

5️⃣ Fix permissions (Linux/Mac)

6️⃣ Run the app

Access: http://localhost:8001

🪝 Husky (Git Hooks)

The project uses Husky to enforce pre-commit and pre-push checks (lint, tests, commit validation).

Setup

After dependencies installation:

Do not overwrite existing hooks — this repository already includes custom pre-commit and pre-push scripts.

If Husky overwrites them, restore:

🛠️ Database Configuration

PostgreSQL 16 is the default database. Created automatically on first container startup.

To access manually inside the container:

🧩 Fix Access Permissions (Spatie Permission Cache)

If a user has correct permissions in the database but still receives:

“You do not have permission to perform this action.”

Run inside the container:

Versions <5.x:

📌 Key Features

• Laravel 13 — Modular, RESTful backend
• Vue 3 + Quasar — Modern reactive UI
• Spatie Permission — Role & permission system
• Spatie Activity Log — Transparent audit trail
• PestPHP — Expressive test framework
• Larastan + PHP Insights — Static analysis & code quality
• Scramble — Automatic API documentation
• Pulse + Telescope + Debugbar + Horizon — Monitoring and debugging

⚙️ Technology Stack

• Backend: Laravel 13 (PHP 8.5 on Alpine)
• Frontend: Vue 3.5 + Quasar Framework + Vite
• Database: PostgreSQL 16
• Cache/Queue: Redis 7
• Mail: Mailpit (SMTP emulator)
• Containerization: Docker Compose
• Testing: PestPHP
• Static Analysis: Larastan
• Monitoring: Pulse, Telescope, Debugbar, Horizon

🚢 Preparing for production

This repository is configured primarily for local development. Before using it in production, apply the following changes:

1. Use a production Compose/deployment configuration without bind mounts from the host and build the frontend assets during the image build.
2. Set APP_ENV=production, APP_DEBUG=false, a unique APP_KEY, and production-specific values for the database, Redis, mail and application URL.
3. Replace the development PHP configuration with docker/PHP/php-prd.ini, disable Xdebug and run the application with a non-development process configuration.
4. Store passwords, encryption keys and tokens in the deployment secret manager; never copy .env.example values directly to production.
5. Restrict CORS and SANCTUM_STATEFUL_DOMAINS to the real frontend domains, enable HTTPS and configure trusted proxies correctly.
6. Do not expose Telescope, Horizon, Pulse or Scramble publicly without authentication and an explicit production access policy.
7. Configure persistent logs, queue workers, scheduler execution, database backups and health checks before accepting traffic.

⚙️ Queues and Horizon Monitoring

The Starter Kit integrates Redis queues and Laravel Horizon for distributed asynchronous job execution and real-time monitoring.

🧠 How It Works

• Jobs are dispatched using Redis queues via queue:work.
• Supervisor automatically manages the worker lifecycle (restart, retry, timeout).
• Horizon provides a dashboard for job tracking, performance metrics, and failure insights.

Example Job Dispatch

Each queue runs independently, enabling parallel processing and load distribution.

Supervisor Configuration Example

• --tries: number of attempts before failure logging.
• --max-time: ensures workers restart periodically to prevent memory leaks.
• --daemon: keeps workers running persistently.

Access Horizon Dashboard

Access is restricted to admin users only in all environments (local, staging, production).

Authorization defined in:

Horizon Features

• Real-time job and queue stats
• Retry failed jobs
• Queue balancing and prioritization
• Job execution metrics and runtime distribution

Recommended Practices

• Name queues descriptively (imports, emails, notifications)
• Split heavy operations into chunks (chunk(100))
• Avoid complex listeners — isolate logic in jobs
• Use Bus::batch() for large batch operations

🚀 Project Architecture

Applies Action Pattern for isolated business logic and Event-Driven Design (EDD) for asynchronous processes.

🧱 Docker Services

All services are defined in docker-compose.yaml.

🧪 Testing

1️⃣ Test Database

If starterkit_test is not created automatically, run:

2️⃣ Run Tests

With coverage:

Parallel mode:

🧠 Best Practices

Security

• APP_DEBUG=false in production
• Generate unique APP_KEY
• Protect routes with auth:sanctum
• Mask sensitive logs

Performance

• Cache queries (tagged TTLs)
• Optimize autoloaders/config caches
• Use DB::transaction() for atomicity

Code Quality

• Maintain ≥80% coverage
• Run Larastan + PHP Insights regularly
• Keep controllers thin; logic in Actions

🔄 Commit Conventions

Follow Conventional Commits.

Types: feat, fix, docs, refactor, test, perf, build, ci, ops, chore, revert

📝 Code Standards

• declare(strict_types=1); required
• Method names ≤ 5 words
• Use imperative verbs
• Variables in camelCase
• Routes follow {resource}.{action}
• API versioning /api/v1/...
• Coverage ≥ 80 lines

Static Analysis

Code Quality

PHP Insights is not currently installed in this starter kit.

API Documentation

Tests

⚡ Makefile Shortcuts