Modular Livewire Laravel Package

Technical Evaluation

Architecture Fit

• Modular Laravel Synergy: Perfectly complements internachi/modular by extending its plugin architecture to Livewire, enabling feature-scoped component organization (e.g., billing::invoice-table). This aligns with microservices-inspired Laravel where modules encapsulate domain logic, including frontend components.
• Livewire’s Reactive Model: Leverages Livewire’s server-driven reactivity while decoupling component registration from core framework concerns. Reduces global namespace pollution, critical for large-scale apps with 100+ components.
• Plugin-Based Extensibility: The package’s design allows for future plugins (e.g., auto-discovery for Inertia.js, Vue) without modifying the core. Lowers technical debt for teams adopting modular patterns.

Integration Feasibility

• Zero-Config Installation: Laravel’s package discovery handles registration automatically, reducing human error in setup.
• Convention Over Configuration: Requires src/Livewire/ per module, which may conflict with existing monolithic Livewire structures or custom directory layouts.
• Naming Constraints: Kebab-case/dot-notation conversion is predictable but rigid. Teams with non-standard naming (e.g., PascalCase in Blade) will need pre-processing (e.g., custom naming resolvers).

Technical Risk

• Dependency Fragility:
  • Hard dependency on internachi/modular v3.0+ and Livewire 3.x could block upgrades if these evolve incompatibly.
  • No backward compatibility: Existing global Livewire components must be explicitly migrated.
• Discovery Edge Cases:
  • False Positives: Non-Livewire classes in src/Livewire/ may register, requiring whitelisting or validation.
  • Path Resolution: Nested modules (e.g., app-modules/billing/src/Livewire/Reports/) must correctly resolve to billing::reports.component.
  • Dynamic Modules: Runtime-loaded modules (e.g., plugins) may not trigger discovery unless event-driven (e.g., ModulesDiscovered event).
• Performance:
  • Startup Overhead: Scanning modules on boot could slow large apps. Mitigate with lazy-loading or caching.
  • Memory Usage: Holding all components in memory may impact apps with thousands of modules.
• Testing Gaps:
  • Unproven Stability: 0 stars/dependents and placeholder changelog suggest limited real-world validation.
  • No Benchmarks: Unknown performance impact under load (e.g., 500+ components).

Key Questions

1. Module Strategy:
   • Are modules static (defined in config/modules.php) or dynamic (loaded via plugins)? Dynamic modules may need custom discovery hooks.
2. Livewire Version:
   • Is Livewire 3.x already in use, or will this require an upgrade path (e.g., from v2)?
3. Component Lifecycle:
   • Are components versioned with modules? If not, how will deprecated components be handled?
4. Customization Needs:
   • Are there requirements for conditional registration (e.g., feature flags) or runtime component resolution?
5. CI/CD Impact:
   • How will module scanning affect test suites (e.g., phpunit.xml configuration)?
   • Are there deployment risks if discovery fails (e.g., missing src/Livewire/ in a module)?
6. Fallback Mechanism:
   • What’s the rollback plan if auto-discovery fails? Manual registration or a hybrid approach?
7. Security:
   • Could auto-discovery expose unintended components (e.g., debug tools) in production? Need whitelisting?

Integration Approach

Stack Fit

• Laravel 11+: Optimized for Laravel’s improved package discovery and first-party Livewire integration. Avoids legacy quirks (e.g., manual service provider binding).
• PHP 8.3+: Leverages modern features (e.g., attributes, enums) for cleaner component metadata handling.
• Livewire 3.x: Aligns with Livewire’s server-side reactivity and Blade integration, ensuring seamless UX.
• Modular Ecosystem: Works alongside internachi/modular’s dependency injection, events, and migration systems for end-to-end modularity.

Migration Path

1. Assessment Phase:
   • Audit Livewire components: Categorize as modularizable (move to src/Livewire/) or legacy (keep global with warnings).
   • Inventory modules: Ensure internachi/modular is configured for auto-loading (e.g., config/modules.php).
2. Pilot Migration:
   • Select low-risk modules (e.g., settings, notifications) to test discovery.
   • Update Blade templates to use module-prefixed names (e.g., <livewire:billing::invoice-table />).
3. Incremental Rollout:
   • Phase 1: Migrate non-critical components. Use feature flags to toggle between old/new registration.
   • Phase 2: Deprecate global registrations. Update AppServiceProvider to fallback only for unmigrated components.
   • Phase 3: Remove legacy registration logic entirely.
4. Validation:
   • Unit Tests: Verify component discovery for edge cases (e.g., hyphenated module names, nested paths).
   • E2E Tests: Confirm Blade rendering, props, and reactivity work across modules.
   • Performance Tests: Measure boot time and memory usage with scaled module counts.

Compatibility

• Breaking Changes:
  • Global Livewire components must be migrated to modules. Plan for downtime if components are tightly coupled to legacy registration.
  • Custom naming schemes (e.g., Livewire::component('custom.name', ...)) will fail unless adapted.
• Forward Compatibility:
  • Monitor internachi/modular for changes to plugin discovery or module loading.
  • Watch Livewire for breaking changes in component resolution (e.g., namespace handling).
• Edge Cases:
  • Hyphenated Module Names: my-module::component may fail if the package doesn’t handle hyphens. Test with config/modules.php aliases.
  • Dynamic Components: If using Livewire::component() dynamically, update to use module-prefixed strings.
  • Shared Components: Components used across modules may need explicit exports or shared module dependencies.

Sequencing

1. Dependency Setup:

   composer require internachi/modular-livewire internachi/modular:^3.0 livewire/livewire:^3.0 --dev
   

   • Pin versions in composer.json to avoid unexpected upgrades.
2. Module Refactoring:
   • Create src/Livewire/ in target modules. Move components, renaming classes to kebab-case (e.g., InvoiceTable.php → invoice-table).
   • Update config/modules.php to ensure modules are auto-loaded.
3. Registration Testing:
   • Use php artisan livewire:discover (if available) or manually verify components register via:

     Livewire::getComponents(); // Check for module-prefixed keys
     

4. Blade Template Updates:
   • Replace <livewire:old-name /> with <livewire:module::component />.
   • Use IDE refactoring tools to automate replacements.
5. Fallback Implementation:
   • In AppServiceProvider, add a safety net for unmigrated components:

     Livewire::component('legacy.name', \LegacyComponent::class);
     

6. Deprecation:
   • Log warnings for legacy components. Gradually remove fallback registrations.

Operational Impact

Maintenance

• Reduced Boilerplate:
  • No manual Livewire::component() calls in service providers. Components are self-registering.
  • Lower cognitive load for onboarding new developers (conventions > configuration).
• Module Isolation:
  • Changes to a module’s Livewire components won’t ripple to others. Enables team autonomy.
  • Easier debugging: Component issues are scoped to their module.
• Dependency Updates:
  • Monitor internachi/modular and Livewire for breaking changes in discovery or registration.
  • Test upgrades in staging before production (e.g., Livewire 4.x support added in v1.1.0).
• Documentation:
  • Internal runbooks needed for:
    • Troubleshooting discovery failures (e.g., missing src/Livewire/).
    • Customizing naming conventions (e.g., for hyphenated modules).
    • Performance tuning (e.g., caching module scans).

Support

• Common Issues:
  • Component Not Found: Verify src/Livewire/ exists and class names follow kebab-case.
  • Naming Conflicts: Check for duplicate module/component names (