Livewire Tweak Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require emkcloud/livewire-tweak
   

   Ensure your project meets the requirements (Laravel 12/13, Livewire 3.7/4.2, and optionally Livewire Flux).

2. Environment Setup Add your custom prefix (e.g., /admin) to .env:

   LIVEWIRE_TWEAK_PREFIX=/admin
   

   No config publishing is required unless customizing beyond defaults.

3. First Use Case Deploy Livewire components in a load-balanced environment with a custom URL prefix (e.g., yourdomain.com/admin). The package automatically adjusts asset paths and API calls to work seamlessly with the prefix.

Implementation Patterns

Core Workflows

1. Prefix-Aware Livewire Components

   • Deploy Livewire components under a custom prefix (e.g., /admin) without manual path adjustments.
   • Example: A Livewire component in /admin/dashboard will generate correct asset URLs like /admin/livewire/livewire.js instead of /livewire/livewire.js.

2. Middleware Integration

   • Use the provided middleware (LivewireTweakMiddleware) to enforce prefix rules for specific routes or globally.
   • Example in app/Http/Kernel.php:

     protected $middlewareGroups = [
         'web' => [
             \Emkcloud\LivewireTweak\Middleware\LivewireTweakMiddleware::class,
             // ... other middleware
         ],
     ];
     

3. Flux-Specific Tweaks

   • If using Livewire Flux, configure the package to adjust Flux’s asset paths and API endpoints:

     LIVEWIRE_TWEAK_FLUX_PREFIX=/backend
     

   • Flux PRO users can similarly customize PRO-specific paths.

4. Blade Directive Overrides

   • Leverage the @livewireStyles and @livewireScripts directives with the package’s tweaks:

     @livewireStyles
     @livewireScripts
     

   • These will automatically resolve to prefixed paths (e.g., /admin/livewire/livewire.js).

Integration Tips

• Load Balancers/Firewalls: Ideal for environments where traffic is routed via prefixes (e.g., /admin, /customers).
• Multi-Tenant Apps: Use different prefixes per tenant (e.g., tenant1.yourdomain.com/admin).
• Testing: Test Livewire components in a prefixed route (e.g., http://localhost:8000/admin) to verify asset paths and API calls work correctly.
• Asset Versioning: The package respects Laravel’s asset versioning (e.g., livewire.js?id=1234), so no additional config is needed.

Gotchas and Tips

Pitfalls

1. Missing Prefix in .env

   • If LIVEWIRE_TWEAK_PREFIX is unset, the package falls back to default behavior (no prefix). Ensure it’s explicitly defined for prefixed environments.
   • Fix: Always set the prefix, even if empty (LIVEWIRE_TWEAK_PREFIX=/).

2. Conflicting Middleware

   • If other middleware (e.g., TrustedProxy) modifies the request path before LivewireTweakMiddleware runs, prefix adjustments may fail.
   • Fix: Order middleware correctly in app/Http/Kernel.php:

     $middleware = [
         \Emkcloud\LivewireTweak\Middleware\LivewireTweakMiddleware::class,
         \GrahamCampbell\TrustedProxy\TrustedProxyMiddleware::class,
         // ...
     ];
     

3. Flux-Specific Issues

   • Flux’s asset paths may still break if the package isn’t configured for Flux (even if Flux is installed).
   • Fix: Explicitly set LIVEWIRE_TWEAK_FLUX_PREFIX if using Flux:

     LIVEWIRE_TWEAK_FLUX_PREFIX=/backend
     

4. Caching Headaches

   • Browser/asset caching may serve stale prefixed/unprefixed assets during testing.
   • Fix: Clear caches and use hard refresh (Ctrl+F5) when testing prefix changes.

5. Livewire 3 vs. 4

   • The package supports both Livewire 3 and 4, but some internal behavior (e.g., asset paths) differs slightly.
   • Tip: Test in both versions if migrating or supporting legacy code.

Debugging Tips

1. Log Prefix Adjustments Enable debug logging to verify prefix adjustments:

   LIVEWIRE_TWEAK_DEBUG=true
   

   Check logs for entries like:

   [LivewireTweak] Adjusted Livewire asset path from '/livewire.js' to '/admin/livewire.js'
   

2. Inspect Generated HTML Use browser dev tools to verify @livewireStyles and @livewireScripts output the correct prefixed paths.

3. API Call Verification Check Livewire’s internal API calls (e.g., livewire/updates) in the Network tab. Ensure they use the prefixed endpoint (e.g., /admin/livewire/updates).

Extension Points

1. Custom Prefix Logic Extend the package’s prefix logic by binding your own resolver:

   LivewireTweak::extend(function ($request) {
       return $request->segment(1) === 'custom' ? '/custom' : config('livewire-tweak.prefix');
   });
   

2. Middleware Customization Override the default middleware behavior by publishing and modifying the config:

   php artisan vendor:publish --tag=livewire-tweak:config
   

   Then extend LivewireTweakMiddleware in app/Http/Middleware/LivewireTweakMiddleware.php.

3. Blade Directive Overrides Register custom Blade directives that leverage the package’s prefix logic:

   Blade::directive('customLivewireScripts', function () {
       return "<?php echo \\Emkcloud\\LivewireTweak\\LivewireTweak::scripts(); ?>";
   });