Wire Bridge Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require mwguerra/wire-bridge
   npm install @wire-bridge/vue @wire-bridge/react
   

   Add to vite.config.js:

   import { defineConfig } from 'vite';
   import laravel from 'laravel-vite-plugin';
   import wireBridge from '@wire-bridge/vite';
   
   export default defineConfig({
       plugins: [
           laravel({
               input: ['resources/css/app.css', 'resources/js/app.js'],
               refresh: true,
           }),
           wireBridge(),
       ],
   });
   

2. First Use Case: Livewire + Vue Bridge

   • Create a Livewire component (php artisan make:livewire MyComponent).
   • In your Vue component:

     <script setup>
     import { useLivewire } from '@wire-bridge/vue';
     
     const { data, set } = useLivewire('my-component', {
         // Initial props
         name: 'John Doe',
     });
     
     // Two-way binding works automatically
     const updateName = () => set({ name: 'Jane Doe' });
     </script>
     

3. First Use Case: Livewire + React Bridge

   import { useLivewire } from '@wire-bridge/react';
   
   function MyComponent() {
       const { data, set } = useLivewire('my-component', {
           name: 'John Doe',
       });
   
       const handleChange = () => {
           set({ name: 'Jane Doe' });
       };
   
       return <input value={data.name} onChange={handleChange} />;
   }
   

Implementation Patterns

Core Workflow: State Management

1. Livewire as State Source

   • All Livewire public properties ($name, $count) are exposed as data in the JS component.
   • Changes in Vue/React automatically sync to Livewire via set().
   • Example:

     <script setup>
     const { data } = useLivewire('my-component');
     // data.name, data.count are reactive
     </script>
     

2. Event Handling

   • Emit Livewire events from JS:

     const emit = useLivewire('my-component').emit;
     emit('customEvent', { payload: 'data' });
     

   • Listen in Livewire:

     public function customEvent($payload) {
         $this->dispatch('js-event', payload: $payload);
     }
     

3. Form Handling

   • Use set() for form submissions:

     const handleSubmit = () => {
         set({ email: 'test@example.com' });
         // Livewire will handle validation/processing
     };
     

Integration Patterns

1. Filament 5 Support

   • Use useLivewire() in Filament panels:

     <script setup>
     const { data } = useLivewire('filament.resource', {
         resource: 'PostResource',
         record: 1,
     });
     </script>
     

2. Third-Party Libraries

   • Libraries like vue-draggable or react-chartjs-2 work as-is:

     <script setup>
     import { Draggable } from 'vue-draggable';
     const { data } = useLivewire('drag-component');
     </script>
     
     <Draggable v-model="data.items" />
     

3. Artisan Generators

   • Scaffold Livewire + Vue/React components:

     php artisan wire:make MyComponent --vue --react
     

Advanced Patterns

1. Nested State

   • Deeply nested objects sync automatically:

     <script setup>
     const { data } = useLivewire('nested-component');
     // data.user.profile.name updates Livewire
     </script>
     

2. Optimistic Updates

   • Update JS state immediately, sync later:

     const setOptimistic = (key, value) => {
         data[key] = value; // JS updates first
         set({ [key]: value }); // Sync to Livewire
     };
     

3. Conditional Binding

   • Use v-if/v-show with Livewire data:

     <div v-if="data.isActive">Active Content</div>
     

Gotchas and Tips

Common Pitfalls

1. Initialization Timing

   • Issue: useLivewire() may not be ready on component mount.
   • Fix: Use onMounted or check data for undefined:

     onMounted(() => {
         if (!data) return;
         // Safe to use data here
     });
     

2. Circular References

   • Issue: Deeply nested objects with circular references may break sync.
   • Fix: Flatten data or use JSON.parse(JSON.stringify()) for cleanup.

3. Event Conflicts

   • Issue: Livewire events (@wire:init, @wire:ignore) may conflict with Vue/React lifecycle.
   • Fix: Prefix custom events or use namespacing:

     @wire:custom-event="handleEvent"
     

4. Vite Auto-Import

   • Issue: Custom Livewire components aren’t auto-imported.
   • Fix: Manually import or configure vite.config.js:

     wireBridge({
         livewire: ['my-component', 'another-component'],
     });
     

Debugging Tips

1. Check Sync State

   • Log data changes to verify sync:

     watch(data, (newVal) => {
         console.log('Livewire data updated:', newVal);
     }, { deep: true });
     

2. Livewire Logs

   • Enable Livewire logging in config/livewire.php:

     'log' => env('LIVEWIRE_LOG', true),
     

3. Network Tab

   • Inspect XHR requests for Livewire updates in DevTools.

Configuration Quirks

1. State Persistence

   • Default: Enabled for all Livewire components.
   • Disable: Pass persist: false in useLivewire():

     useLivewire('my-component', { persist: false });
     

2. Custom Serialization

   • Override default serialization for complex types:

     // In Livewire component
     public function serialize($property) {
         return match ($property) {
             'complexData' => json_encode($this->complexData),
             default => parent::serialize($property),
         };
     }
     

3. Vite Build Modes

   • Issue: Dev vs. production builds may behave differently.
   • Fix: Test in both modes; use import.meta.env.MODE for conditional logic.

Extension Points

1. Custom Hooks

   • Extend useLivewire() with custom logic:

     const { data, set, emit } = useLivewire('my-component');
     const customHook = (payload) => {
         set({ customField: payload });
         emit('customEvent', payload);
     };
     

2. Middleware

   • Add middleware to useLivewire() calls:

     // vite.config.js
     wireBridge({
         middleware: (wire) => {
             wire.data = { ...wire.data, timestamp: Date.now() };
             return wire;
         },
     });
     

3. TypeScript Support

   • Define types for Livewire props:

     interface MyComponentProps {
         name: string;
         count: number;
     }
     const { data } = useLivewire<MyComponentProps>('my-component');