Blank Livewire Starter Kit Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer create-project laravel/blank-livewire-starter-kit my-project
   cd my-project
   npm install && npm run dev  # Install and build Tailwind assets
   

2. First Use Case: Create a Livewire Component Generate a new Livewire component with Blade scaffolding:

   php artisan make:livewire Counter
   

   This creates:

   • app/Livewire/Counter.php (PHP logic)
   • resources/views/livewire/counter.blade.php (Blade template)

3. Where to Look First

   • app/Http/Livewire/: Default namespace for Livewire components.
   • resources/views/layouts/app.blade.php: Base layout with Tailwind directives.
   • tailwind.config.js: Tailwind configuration (if customizing styles).
   • webpack.mix.js: Asset compilation setup (if extending frontend).

Implementation Patterns

Core Workflows

1. Component-Based Development

   • Pattern: Treat Livewire components as modular units (e.g., UserProfile, DashboardStats).
   • Example:

     // app/Livewire/UserProfile.php
     public $name;
     public function updateProfile() {
         $this->validate(['name' => 'required']);
         // Update logic...
     }
     

     <!-- resources/views/livewire/user-profile.blade.php -->
     <input wire:model="name" type="text">
     <button wire:click="updateProfile">Save</button>
     

2. Reusability with Props and Events

   • Pass data via props:

     public $userId;
     public function mount($userId) { $this->userId = $userId; }
     

   • Emit events for parent components:

     $this->emit('userUpdated', $userId);
     

     <script>
         document.addEventListener('livewire:init', () => {
             Livewire.on('userUpdated', userId => {
                 console.log(`User ${userId} updated!`);
             });
         });
     </script>
     

3. State Management

   • Leverage Livewire’s reactive properties for form state:

     public $search = '';
     public function searchUsers() {
         $this->users = User::where('name', 'like', "%{$this->search}%")->get();
     }
     

   • Avoid over-fetching: Use wire:ignore for static DOM elements.

4. Integration with Laravel Features

   • Authentication: Extend with laravel/breeze or laravel/jetstream (not included by default).
   • APIs: Use Livewire’s $this->dispatchBrowserEvent() for real-time updates:

     $this->dispatchBrowserEvent('alert', ['type' => 'success', 'message' => 'Updated!']);
     

     <script>
         window.addEventListener('alert', event => {
             toast.fire({ icon: event.detail.type, title: event.detail.message });
         });
     </script>
     

5. Testing

   • Unit tests: Use Livewire::test() in PHPUnit:

     public function test_counter_increments() {
         $component = Livewire::test(Counter::class);
         $component->increment();
         $component->assertSet('count', 1);
     }
     

   • Browser tests: Combine with Laravel Dusk for full-stack testing.

Gotchas and Tips

Pitfalls

1. Tailwind Conflicts

   • Issue: Tailwind classes may not apply due to missing @layer directives or incorrect build order.
   • Fix: Ensure tailwind.config.js includes all necessary paths and run npm run dev after changes.

2. Livewire Wire:Key Misuse

   • Issue: Forgetting wire:key on dynamic components causes hydration errors.
   • Fix: Always use a unique key for dynamic elements:

     @foreach($items as $item)
         <div wire:key="item-{{ $item->id }}">
             {{ $item->name }}
         </div>
     @endforeach
     

3. State Persistence

   • Issue: Livewire state resets on page refresh (unlike JavaScript SPAs).
   • Fix: Use Laravel sessions or database-backed state for critical data.

4. Overusing Livewire for Static Content

   • Issue: Adding Livewire to non-interactive elements bloats the DOM.
   • Fix: Use wire:ignore for static sections or consider plain Blade.

5. Debugging Tips

   • Livewire Logs: Enable debug mode in .env:

     LIVEWIRE_LOG_LEVEL=debug
     

   • Browser DevTools: Inspect network requests for Livewire’s __livewire payloads.
   • XHR Breakpoints: Pause Livewire updates in Chrome DevTools under "Network" > "XHR".

Extension Points

1. Custom Directives Extend Livewire’s JavaScript with custom directives (e.g., for animations):

   // resources/js/livewire.js
   document.addEventListener('livewire:init', () => {
       Livewire.directive('fade', (el, { expression }) => {
           el.style.transition = 'opacity 0.3s';
           el.style.opacity = expression ? '1' : '0';
       });
   });
   

   <div wire:fade="{{ $show }}">Content</div>
   

2. Middleware for Livewire Protect Livewire components with middleware:

   // app/Http/Middleware/CheckRole.php
   public function handle($request, Closure $next) {
       if (!auth()->user()->isAdmin) {
           abort(403);
       }
       return $next($request);
   }
   

   // app/Livewire/AdminDashboard.php
   public function middleware() {
       return [\App\Http\Middleware\CheckRole::class];
   }
   

3. Hybrid Blade + Livewire Combine static Blade with dynamic Livewire:

   <div class="static-content">
       <!-- Plain Blade -->
       <h1>Welcome, {{ auth()->user()->name }}</h1>
   </div>
   
   @livewire('dynamic-content', ['user' => auth()->user()])
   

4. Performance Optimization

   • Lazy Loading: Use wire:init for non-critical components:

     @livewire('heavy-component', key('heavy-component'), only: ['mount'])
     

   • Debounce Inputs: Reduce server calls for rapid user input:

     public $search;
     protected $listeners = ['debouncedSearch' => 'searchUsers'];
     
     public function updatedSearch($value) {
         $this->dispatch('debouncedSearch')->after(500);
     }
     

5. Configuration Quirks

   • Livewire Publish: Customize Livewire’s assets:

     php artisan vendor:publish --provider="Livewire\LivewireServiceProvider"
     

   • Tailwind JIT: Ensure tailwind.config.js is configured for JIT mode if using @apply.