README

A comprehensive performance optimization toolkit for Laravel applications. Image optimization, JS/CSS strategies, resource hints, speculative loading, page and fragment caching, database query analysis, and a real-user performance monitoring dashboard — with Livewire, React, and Vue front-ends.

Highlights

🖼 Image optimization — WebP/AVIF conversion, responsive sizes, dominant-color LQIP, lazy loading
⚡ JS & CSS strategies — deferred / async / conditional scripts, critical CSS extraction, HTML minification
🔮 Speculative loading — Speculation Rules API for prefetch and prerender
🔗 Resource hints & Early Hints — preconnect, dns-prefetch, preload, HTTP 103 Early Hints
🗄 Caching — page cache, fragment cache, tag-based invalidation, cache warming
🧮 Database optimization — N+1 detection, slow query logging, query cache, index suggestions
📊 Real-user monitoring — Web Vitals collection, aggregation, and a Livewire admin dashboard
🧰 Artisan tooling — perf:install, perf:warm-cache, perf:purge-cache, perf:aggregate-metrics, perf:critical-css, perf:generate-webp, perf:suggest-indexes
🎛 Every feature is opt-in — nothing runs until you toggle it on

Requirements

PHP 8.2+ for Laravel 10, 11, or 12
PHP 8.3+ for Laravel 13
ext-gd or ext-imagick for image optimization
Livewire 3 (optional — only required for the bundled dashboard components)

Installation

composer require artisanpack-ui/performance
php artisan perf:install

The install command publishes config, runs migrations, validates environment requirements, and prints the dashboard gate stub plus next steps.

Non-interactive install (CI/CD)

php artisan perf:install --no-interaction --force

React / Vue projects

Front-end companion is published as @artisanpack-ui/performance with subpath exports:

// React
import { PerformanceDashboard, MetricsChart } from '@artisanpack-ui/performance/react'

// Vue
import MetricsChart from '@artisanpack-ui/performance/vue/MetricsChart.vue'

// Vanilla helpers
import { reportWebVitals } from '@artisanpack-ui/performance/web-vitals'
import { applySpeculativeRules } from '@artisanpack-ui/performance/speculative-rules'

The React/Vue components hit the same JSON API the Livewire dashboard does, so back-end behavior is identical regardless of the chosen front-end.

Quick start

{{-- Drop the RUM collector into your layout --}}
@perfMonitor

{{-- Emit Speculation Rules for a prefetch/prerender ruleset --}}
@speculativeRules('main-nav')

{{-- Render the admin dashboard behind your gate --}}
<livewire:performance-dashboard />

use ArtisanPackUI\Performance\Facades\Performance;

// Convert an image to WebP + AVIF and generate responsive sizes
Performance::optimizeImage($path, [
    'sizes'   => [320, 640, 1024],
    'formats' => ['webp', 'avif'],
]);

// Cache a fragment for 10 minutes, tagged for invalidation
$html = Performance::fragmentRemember('product.card.'.$product->id, 600, function () use ($product) {
    return view('products.card', ['product' => $product])->render();
}, tags: ['product:'.$product->id]);

// Register a script with a load strategy
Performance::script(asset('js/analytics.js'))
    ->name('analytics')
    ->defer()
    ->loadOn('interaction');

Documentation

docs/home.md — documentation home
docs/guides.md — feature walkthroughs
docs/api.md — programmatic API reference

Feature guides

API reference

Benchmarks

Customization

Security

Development

Artisan commands

Command	Purpose
`perf:install`	Publish config, migrate, validate environment, print gate stub
`perf:warm-cache`	Pre-populate page/fragment cache for configured URLs
`perf:purge-cache`	Flush the page and/or fragment cache (optional tag filters)
`perf:aggregate-metrics`	Roll raw RUM samples up into hourly/daily buckets
`perf:critical-css`	Extract critical CSS for configured routes
`perf:generate-webp`	Batch-convert existing images to WebP/AVIF
`perf:suggest-indexes`	Analyze slow queries and suggest missing indexes

Schedule the recurring commands in bootstrap/app.php (Laravel 11+):

->withSchedule(function (Schedule $schedule): void {
    $schedule->command('perf:aggregate-metrics')->hourly();
    $schedule->command('perf:warm-cache')->everyThirtyMinutes();
    $schedule->command('perf:suggest-indexes')->daily();
})

Testing

composer test                                # full suite
./vendor/bin/pest tests/Feature/Cache        # one suite
./vendor/bin/pest --filter=speculative       # one test
composer bench                               # benchmark suite (opt-in)

The package ships with 800+ Pest tests covering every service, model, Livewire component, Artisan command, middleware, event, and listener.

Configuration

Every feature toggle in config/artisanpack/performance.php has a matching PERF_* environment variable, so you can flip features per environment without code changes:

'features' => [
    'image_optimization'  => env('PERF_IMAGE_OPTIMIZATION', false),
    'script_optimization' => env('PERF_SCRIPT_OPTIMIZATION', false),
    'critical_css'        => env('PERF_CRITICAL_CSS', false),
    'resource_hints'      => env('PERF_RESOURCE_HINTS', false),
    'speculative_loading' => env('PERF_SPECULATIVE_LOADING', false),
    'html_minification'   => env('PERF_HTML_MINIFICATION', false),
    'early_hints'         => env('PERF_EARLY_HINTS', false),
    'page_cache'          => env('PERF_PAGE_CACHE', false),
    'fragment_cache'      => env('PERF_FRAGMENT_CACHE', false),
    'cache_warming'       => env('PERF_CACHE_WARMING', false),
    'query_optimization'  => env('PERF_QUERY_OPTIMIZATION', false),
    'monitoring'          => env('PERF_MONITORING', false),
    'dashboard'           => env('PERF_DASHBOARD', false),
],

The published configuration file is heavily commented — every section documents what it does and the trade-offs of each option.

Upgrading

See CHANGELOG.md for release history. Version-to-version upgrade notes will land in UPGRADING.md once there is a v1.x → v2.x transition to document.

Contributing

As an open source project, this package is open to contributions from anyone. Please read through the contributing guidelines to learn more about how you can contribute to this project.

License

MIT — see LICENSE.

artisanpack-ui/performance

包简介

README 文档