Laravel Modules Livewire Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require xslain/laravel-modules-livewire
   php artisan vendor:publish --tag=modules-livewire-config
   

   • Verify config/modules-livewire.php exists in your project.

2. Generate a Livewire Component:

   php artisan pagemodule:make-livewire Pages/AboutPage Core
   

   • This creates a Livewire component (AboutPage) inside the Core module, auto-registered for Livewire.

3. Use the Component:

   @livewire('core::pages.about-page')
   

   • The :: syntax ensures the component is resolved from the Core module.

First Use Case

• Modular Livewire Pages: Build a multi-module app where each module (e.g., Core, Admin, Blog) has its own Livewire components. The package auto-discovers and registers them, eliminating manual Livewire component registration.

Implementation Patterns

Workflows

1. Component Organization:

   • Place Livewire components in module-specific directories (e.g., Modules/Core/Http/Livewire/Pages/).
   • Use the pagemodule:make-livewire command to scaffold components with module-aware namespacing.

2. View Binding:

   • The --view= flag lets you specify a custom Blade view path for the component:

     php artisan pagemodule:make-livewire Dashboard/Stats Core --view=modules/core/resources/views/livewire/dashboard/stats.blade.php
     

3. Inline Components:

   • Use the --inline flag to generate a self-contained component (no separate Blade file):

     php artisan pagemodule:make-livewire Widgets/Alert Core --inline
     

4. Custom Stubs:

   • Extend the default stubs by publishing the package’s stubs:

     php artisan vendor:publish --tag=modules-livewire-stubs
     

   • Modify stubs/livewire.stub to include module-specific logic (e.g., middleware, module-specific properties).

5. Dynamic Registration:

   • The package auto-registers components via the ModulesServiceProvider. Override the boot() method in your module’s service provider to add custom logic:

     public function boot()
     {
         $this->app->make(\Xslain\ModulesLivewire\LivewireServiceProvider::class);
         // Custom Livewire middleware or hooks
     }
     

6. Module-Specific Livewire Hooks:

   • Use the livewire:component event to inject module-specific data or middleware:

     // In your module's EventServiceProvider
     public function boot()
     {
         Livewire::component('core::pages.*', function ($component) {
             $component->middleware('auth:admin'); // Example: Module-specific middleware
         });
     }
     

Integration Tips

• Livewire + Modules Middleware: Apply module-specific middleware to Livewire components by leveraging the boot() method in your module’s ServiceProvider:

  Livewire::component('core::*', function ($component) {
      $component->middleware(['auth', 'verified']);
  });
  

• Shared Livewire Logic: Create a base Livewire class in your module (e.g., Modules/Core/Http/Livewire/BaseLivewire.php) and extend it in generated components:

  use Xslain\ModulesLivewire\Traits\HandlesModuleData;
  
  class BaseLivewire extends Livewire
  {
      use HandlesModuleData;
  }
  

• Asset Management: Use module-specific asset paths in Livewire components:

  public function mount()
  {
      $this->moduleAssets = asset('modules/core/assets/');
  }
  

• Testing: Test Livewire components in isolation using Laravel’s Livewire testing helpers:

  $this->livewire('core::pages.about-page')
       ->assertSee('Welcome to About Page');
  

Gotchas and Tips

Pitfalls

1. Component Naming Collisions:

   • Avoid naming conflicts by using module prefixes (e.g., core::pages.about-page vs. blog::posts.index). The package resolves components via module namespace, but ensure uniqueness across modules.

2. Caching Issues:

   • After generating or modifying components, clear Livewire’s view cache:

     php artisan livewire:discover
     php artisan view:clear
     

   • If components aren’t auto-discovered, manually register them in config/livewire.php under component_path.

3. Stub Overrides:

   • Custom stubs must follow the package’s expected structure. Incorrect stubs may break component generation. Test stubs locally before applying globally.

4. Middleware Scope:

   • Module-specific middleware applied via Livewire::component() in boot() only affects components registered after the middleware is set. Use a high-priority service provider to ensure order.

5. Inline Components and Assets:

   • Inline components (--inline) won’t have separate Blade files, so manage assets (CSS/JS) directly in the component class or use @stack directives in the parent layout.

Debugging

1. Component Not Found:

   • Verify the component is generated in the correct module directory (e.g., Modules/Core/Http/Livewire/Pages/).
   • Check the config/modules-livewire.php for custom paths or registration logic.
   • Run php artisan livewire:discover --verbose to debug discovery issues.

2. Livewire Events Not Firing:

   • Ensure the component is properly namespaced (e.g., core::pages.about-page).
   • Check for JavaScript errors in the browser console that might block Livewire’s event system.

3. Configuration Overrides:

   • If publishing the config doesn’t reflect changes, clear the config cache:

     php artisan config:clear
     

Tips

1. Module-Specific Livewire Config: Extend the package’s config to add module-specific Livewire settings:

   // config/modules-livewire.php
   'modules' => [
       'core' => [
           'middleware' => ['auth', 'verified'],
           'namespace' => 'Core\\Http\\Livewire',
       ],
   ],
   

2. Livewire + Modules Events: Listen to module events to dynamically register or modify Livewire components:

   // In your module's EventServiceProvider
   public function boot()
   {
       Modules::firing('Modules\Core\Events\ModuleInitialized', function ($module) {
           Livewire::component('core::dashboard.*', function ($component) {
               $component->module = $module;
           });
       });
   }
   

3. Performance:

   • For modules with many Livewire components, lazy-load them by deferring registration until the module is initialized:

     // In your module's ServiceProvider
     public function boot()
     {
         if (Modules::has('Core')) {
             $this->app->make(\Xslain\ModulesLivewire\LivewireServiceProvider::class);
         }
     }
     

4. Livewire + Inertia: If using Inertia.js, ensure the Livewire component is properly proxied in your Inertia setup. The package doesn’t natively support Inertia, so manually register components in app/Http/Middleware/HandleInertiaRequests.php:

   public function rootView(Request $request)
   {
       return parent::rootView($request)->with([
           'livewireComponents' => [
               'core::pages.about-page' => 'AboutPage',
           ],
       ]);
   }
   

5. Testing Modules: Use Laravel Modules’ testing helpers to isolate Livewire components:

   $this->actingAs($user)
        ->withModule('Core')
        ->livewire('core::pages.about-page')
        ->assertSuccessful();