Laravel Tachyon Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ideal-creative-lab/laravel-tachyon
   

   Publish the config file:

   php artisan vendor:publish --provider="IdealCreativeLab\Tachyon\TachyonServiceProvider" --tag="tachyon-config"
   

2. First Use Case: Enable Tachyon for a specific route or globally in config/tachyon.php:

   'enabled' => env('TACHYON_ENABLED', true),
   

   Add middleware to app/Http/Kernel.php:

   protected $middlewareGroups = [
       'web' => [
           // ...
           \IdealCreativeLab\Tachyon\Middleware\OptimizeHtml::class,
       ],
   ];
   

3. Verify: Visit a page and inspect the response headers for X-Tachyon-Optimized: true.

Implementation Patterns

Core Workflows

1. Selective Optimization: Use route-based middleware groups or middleware aliases to apply Tachyon only to specific routes:

   Route::middleware(['tachyon'])->group(function () {
       Route::get('/optimized-page', [PageController::class, 'show']);
   });
   

2. Livewire Integration: Exclude Livewire components from optimization by wrapping them in a tachyon:ignore directive:

   @tachyon:ignore
       <livewire:component />
   @endtachyon
   

   Or via Blade:

   <div data-tachyon-ignore>
       <livewire:component />
   </div>
   

3. Dynamic Exclusions: Exclude dynamic content (e.g., user-specific data) via config:

   'excluded_selectors' => [
       '.user-specific-data',
       '[data-dynamic]',
   ],
   

4. Conditional Optimization: Disable Tachyon for specific IPs or user agents:

   'skip_for' => [
       'ips' => ['127.0.0.1'],
       'user_agents' => ['MobileApp/1.0'],
   ],
   

Integration Tips

• Blade Directives: Use @tachyon:ignore to exclude blocks from optimization.
• Service Provider: Extend Tachyon’s behavior by binding custom processors in the service provider:

  $this->app->bind(
      \IdealCreativeLab\Tachyon\Contracts\HtmlProcessor::class,
      \App\Services\CustomHtmlProcessor::class
  );
  

• Testing: Mock Tachyon in tests by overriding the middleware or using Tachyon::shouldOptimize(false).

Gotchas and Tips

Pitfalls

1. Caching Headaches:

   • Tachyon modifies HTML dynamically. Ensure your caching layer (e.g., Redis, Varnish) is configured to handle dynamic responses.
   • Fix: Use Cache::forget('html_*') or adjust cache keys to avoid stale content.

2. Livewire Conflicts:

   • Over-optimization may break Livewire’s reactivity. Exclude Livewire components explicitly:

     'livewire_exclusions' => [
         'components' => ['livewire:admin-dashboard'],
         'attributes' => ['wire:init', 'wire:model'],
     ],
     

3. CSS/JS Inlining:

   • Tachyon may inline critical CSS/JS aggressively. Test with tools like WebPageTest to avoid render-blocking issues.
   • Fix: Adjust config/tachyon.php:

     'inline_critical' => false,
     

4. Debugging:

   • Disable Tachyon temporarily for debugging:

     php artisan tachyon:disable
     

   • Check logs for optimization errors:

     tail -f storage/logs/laravel.log | grep Tachyon
     

Tips

1. Performance Tuning:

   • Use tachyon:analyze to profile optimization impact:

     php artisan tachyon:analyze /path-to-view
     

   • Adjust optimization_level (0–10) in config for granular control.

2. Exclusion Strategies:

   • Dynamically exclude content based on user roles or request data:

     Tachyon::excludeIf(fn () => Auth::user()->isAdmin());
     

3. Custom Processors:

   • Extend Tachyon’s core logic by creating a custom processor:

     namespace App\Services;
     use IdealCreativeLab\Tachyon\Contracts\HtmlProcessor;
     
     class CustomProcessor implements HtmlProcessor {
         public function process(string $html): string {
             // Custom logic (e.g., lazy-load images)
             return $html;
         }
     }
     

4. Environment Awareness:

   • Disable Tachyon in config/tachyon.php for local/staging:

     'enabled' => app()->environment(['production']),
     

5. Blade Debugging:

   • Use @tachyon:debug to inspect optimized HTML:

     @tachyon:debug
         <div>Content to debug</div>
     @endtachyon