Livewiremesh Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ethanbarlo/livewiremesh
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="EthanBarlo\LivewireMesh\LivewireMeshServiceProvider"
   

2. First Use Case: Add the package to a Livewire component:

   use EthanBarlo\LivewireMesh\LivewireMesh;
   
   public function mount()
   {
       LivewireMesh::mount('MyReactComponent', [
           'prop1' => $this->someProperty,
           'prop2' => $this->anotherProperty,
       ]);
   }
   

3. Blade Integration:

   @livewireMesh('MyReactComponent', [
       'prop1' => $this->someProperty,
       'prop2' => $this->anotherProperty,
   ])
   

Where to Look First

• Documentation: Check the README.md for basic examples and API reference.
• Config File: config/livewiremesh.php for package settings (e.g., React build paths, debug mode).
• Service Provider: EthanBarlo\LivewireMesh\LivewireMeshServiceProvider for bootstrapping logic.

Implementation Patterns

Core Workflows

1. Component Mounting:

   • Use LivewireMesh::mount() in Livewire component methods (e.g., mount(), updatedProperty()).
   • Pass reactive props as an associative array:

     LivewireMesh::mount('Counter', ['count' => $this->count]);
     

2. Reactive Updates:

   • Automatically sync Livewire properties to React via updated* hooks:

     public function updatedCount()
     {
         $this->emitToMesh('Counter', 'updateCount', $this->count);
     }
     

3. Event Handling:

   • Listen for React events in Livewire:

     public function handleReactEvent($eventName, $payload)
     {
         // Process payload (e.g., update Livewire state)
     }
     

   • Emit events from React to Livewire:

     // In your React component
     this.$emit('reactEvent', { data: 'payload' });
     

4. Conditional Rendering:

   • Use shouldRender() to control when React components mount:

     public function shouldRender()
     {
         return $this->isReadyToRender;
     }
     

Integration Tips

• Build Process:

  • Configure config/livewiremesh.php to point to your React build output (e.g., public/build/react).
  • Use Laravel Mix/Vite to bundle React components with Livewire-specific entry points.

• TypeScript Support:

  • Extend React types to include LivewireMesh-specific props/events:

    declare module '@livewiremesh/react' {
      interface LivewireMeshProps {
        count: number;
      }
      interface LivewireMeshEvents {
        updateCount: (count: number) => void;
      }
    }
    

• Testing:

  • Mock LivewireMesh in PHPUnit:

    $this->partialMock(LivewireMesh::class, function ($mock) {
        $mock->shouldReceive('mount')->once();
    });
    

Gotchas and Tips

Pitfalls

1. Prop Reactivity:

   • Issue: Nested objects/arrays may not update reactively by default.
   • Fix: Use LivewireMesh::reactive() to mark specific props:

     LivewireMesh::reactive(['nested' => $this->nestedObject]);
     

2. Event Naming Collisions:

   • Issue: React events with the same name as Livewire methods may cause conflicts.
   • Fix: Prefix React events (e.g., react_):

     this.$emit('react_submitForm', { data });
     

3. Build Paths:

   • Issue: Incorrect react_build_path in config may break asset loading.
   • Fix: Verify the path points to your React build output (e.g., public/dist/react).

4. Debugging:

   • Enable debug mode in config to log mesh interactions:

     'debug' => env('APP_DEBUG', false),
     

   • Check browser console for React errors and Livewire logs for PHP-side issues.

Tips

1. Performance:

   • Use LivewireMesh::lazy() to defer mounting until needed:

     LivewireMesh::lazy('HeavyComponent', ['data' => $this->data]);
     

2. State Management:

   • Leverage Livewire’s state for global React props:

     public $globalConfig = ['theme' => 'dark'];
     // Accessible in React via `this.$wire.globalConfig`.
     

3. Custom Hooks:

   • Extend LivewireMesh with custom hooks (e.g., for auth checks):

     LivewireMesh::hook('mount', function ($component, $props) {
         if (!$this->auth->check()) {
             return false; // Skip mounting
         }
         return $props;
     });
     

4. Fallbacks:

   • Provide fallback content for unsupported browsers:

     @livewireMesh('MyComponent', [], fallback: '<p>React not supported</p>')
     

5. Versioning:

   • Pin the package version in composer.json to avoid breaking changes during early adoption:

     "ethanbarlo/livewiremesh": "1.0.0"