Livewire Optimistic Ui Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require capevace/livewire-optimistic-ui
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Capevace\LivewireOptimisticUI\LivewireOptimisticUIServiceProvider"
   

2. First Use Case:

   • Add the <x-optimistic::injector> component to your Livewire blade file.
   • Use x-optimistic directive on elements to mark them as optimistic updates.
   • Example:

     <x-optimistic::injector>
       <div x-optimistic>Loading state...</div>
     </x-optimistic::injector>
     

3. Key Files to Review:

   • resources/views/vendor/livewire-optimistic-ui/ (published views)
   • config/livewire-optimistic-ui.php (configuration)

Implementation Patterns

Core Workflow

1. Form Submission:

   • Use Alpine.js to trigger optimistic updates before Livewire submission:

     <form @submit.prevent="
       $optimistic.addTask(text);
       $wire.submit('store', { text });
     ">
     

   • Pair with wire:loading.delay for smooth transitions.

2. List Management:

   • Use x-optimistic on list items for add/remove/edit operations:

     <div x-optimistic x-optimistic.removed.remove>
       {{ $task['text'] }}
     </div>
     

3. State Management:

   • Leverage Alpine’s reactivity with $optimistic object:

     $optimistic.addTask('New Task'); // Add before Livewire response
     $optimistic.deleteTask('123');   // Remove before Livewire response
     

Integration Tips

• Debouncing: Use @input.debounce for edit operations:

  @input.debounce.500="$optimistic.editTask('{{ $task['id'] }}', text)"
  

• Conditional Rendering: Combine with Alpine’s x-if:

  <div x-optimistic x-if="$optimistic.isPending('editTask-{{ $task['id'] }}')">
    Saving...
  </div>
  

• Livewire Events: Sync with Livewire’s wire:submit/wire:click:

  wire:submit.prevent="store"
  @submit.prevent="$optimistic.addTask(text); $wire.submit()"
  

Gotchas and Tips

Common Pitfalls

1. Missing wire:key:

   • Always include wire:key on dynamic list items to prevent hydration issues:

     <div wire:key="{{ $task['id'] }}">...</div>
     

2. State Collisions:

   • Use unique IDs for optimistic states (e.g., editTask-{{ $task['id'] }}) to avoid conflicts.

3. Alpine vs. Livewire Conflicts:

   • Ensure Alpine’s $optimistic is initialized before Livewire’s wire:init:

     <x-optimistic::injector wire:init="initOptimistic">
       <!-- Content -->
     </x-optimistic::injector>
     

Debugging Tips

• Check Console: Look for Alpine errors (e.g., $optimistic undefined).
• Inspect States: Use $optimistic.getStates() in browser console to debug pending operations.
• Disable Optimistic UI: Temporarily remove x-optimistic directives to isolate issues.

Extension Points

1. Custom States:

   • Extend the $optimistic object in Alpine:

     $optimistic.customState = (id, data) => { /* ... */ };
     

2. Global Config:

   • Override defaults in config/livewire-optimistic-ui.php:

     'default_duration' => 3000, // Auto-remove after 3 seconds
     

3. Server-Side Sync:

   • Handle failed submissions with wire:error:

     @error('store') $optimistic.revert('addTask') @enderror