Laravel Modular Livewire Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alizharb/laravel-modular-livewire
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="AlizHarb\ModularLivewire\ModularLivewireServiceProvider"
   

2. First Use Case: Create a Livewire component inside a module:

   php artisan make:livewire Blog/PostList --module
   

   This generates:

   Modules/Blog/app/Livewire/PostList.php
   Modules/Blog/resources/views/livewire/post-list.blade.php
   

3. Usage in Blade:

   <livewire:blog::post-list />
   

   The package auto-discovers and registers the component under the module namespace (blog::).

Implementation Patterns

1. Component Organization

• Modular Structure: Place Livewire components in Modules/{ModuleName}/app/Livewire/. Example:

  Modules/Blog/app/Livewire/
    ├── PostList.php
    ├── PostCreate.php
    └── ...
  

• Namespace Prefixing: The package auto-prefixes components with the module name (e.g., blog::post-list). Override in config/modular-livewire.php if needed:

  'namespace_prefix' => 'modules.',
  

2. Artisan Workflow

• Generate Components:

  # Inside a module directory
  php artisan make:livewire Admin/UserManager --module
  
  # Or globally (auto-detects module)
  php artisan make:livewire --module Blog/PostList
  

• Run Commands: Use the --module flag to target specific modules:

  php artisan livewire:discover --module=Blog
  

3. Integration with Laravel Modular

• Module Bootstrapping: The package hooks into Laravel Modular’s ModuleServiceProvider to auto-register components when modules boot. No manual registration in AppServiceProvider required.

• Dynamic Module Loading: Components are discovered only when their module is loaded (lazy-loading friendly).

4. View and Asset Management

• Views: Store views in Modules/{ModuleName}/resources/views/livewire/{ComponentName}.blade.php. Example:

  <!-- Modules/Blog/resources/views/livewire/post-list.blade.php -->
  <div>Posts: {{ $posts->count() }}</div>
  

• Assets: Use the module’s asset paths in views:

  <script src="{{ asset('modules/blog/js/post-list.js') }}"></script>
  

5. Testing

• Unit Testing: Mock components using their fully qualified class names:

  $this->livewire(Blog\Livewire\PostList::class);
  

• Feature Testing: Use the module namespace in assertions:

  $this->livewire('blog::post-list')->assertSee('Posts');
  

Gotchas and Tips

Pitfalls

1. Namespace Collisions:

   • If two modules have components with the same name (e.g., Admin/UserList and Blog/UserList), the last discovered module will override the first.
   • Fix: Use unique component names or override the namespace_prefix in config.

2. Caching Issues:

   • After adding a new component, run:

     php artisan livewire:discover --force
     

     to clear the cache and re-register components.

3. Module Not Discovered:

   • Ensure the module’s ModuleServiceProvider is registered in config/app.php under providers.
   • Verify the module’s composer.json includes the Livewire directory in autoload.psr-4:

     "autoload": {
       "psr-4": {
         "Modules\\Blog\\": "Modules/Blog/src/"
       }
     }
     

4. Livewire Publish Not Working:

   • If make:livewire doesn’t generate files in the module, ensure you’re running the command from the project root or specify the module:

     php artisan make:livewire --module=Blog/PostList
     

Debugging

• Check Discovery: Run php artisan livewire:discover --verbose to see which components are being registered.

• Log Component Registration: Enable debug mode in config/modular-livewire.php:

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

Tips

1. Custom Component Paths: Override the default Livewire path in config/modular-livewire.php:

   'component_path' => 'Modules/{ModuleName}/app/Livewire',
   

2. Shared Components: For components shared across modules, place them in a shared module (e.g., Core) and use:

   <livewire:core::shared-component />
   

3. Dynamic Module Loading: Leverage Laravel Modular’s Module::load() to dynamically load components:

   Module::load('Blog');
   // Now <livewire:blog::post-list /> is available
   

4. Performance: The package caches discovered components. For development, disable caching in config/modular-livewire.php:

   'cache_discovered_components' => env('APP_ENV') !== 'local',
   

5. Extending the Package:

   • Custom Discovery: Override AlizHarb\ModularLivewire\Discovery\LivewireDiscoverer to add custom logic.
   • Artisan Commands: Extend the make:livewire command by publishing and modifying the template:

     php artisan vendor:publish --tag=modular-livewire-templates