Filament Flux Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Seamless Flux Integration: Leverages Livewire Flux’s modern UI components (e.g., FluxInput, FluxSelect) while preserving Filament’s native API. This aligns with Laravel’s ecosystem (Filament v5 + Livewire) and avoids reinventing form/field logic.
  • Granular Opt-In: Supports per-field/component replacement (e.g., opt out select fields while adopting FluxInput). Reduces risk of breaking existing UI.
  • Navigation/Shell Overrides: Enables Flux-style sidebar/topbar without rewriting Filament’s data layer (active states, badges, etc.). Ideal for teams prioritizing consistency.
  • Blade Component Replacement: Extends Filament’s atomic components (e.g., <x-flux::badge>, <x-flux::dropdown>) with Flux primitives, reducing custom CSS/JS overhead.
  • Theme Sync: Bridges Filament’s theme switcher with Flux’s appearance store, ensuring cross-tab consistency.

• Cons:

  • Filament v5 Only: Hard dependency on Filament v5 (no backports to v3/v4). Requires migration if using older versions.
  • Feature Gaps: Some Filament-specific affordances (e.g., pageOptions in pagination, extremeLinks) are dropped in Flux replacements. May require workarounds.
  • Modal Limitations: Flux’s free tier lacks <flux:modal>, forcing reliance on Filament’s native modals for actions/confirmations.
  • Icon System Complexity: Mixed icon sets (Heroicons + Font Awesome/Tabler) require a HeroiconNormalizer, adding minor maintenance overhead.

Integration Feasibility

• Low Risk for Greenfield Projects: Designed for Filament v5 panels with minimal existing customizations. The useEverywhere() flag automates bulk replacements.
• Moderate Risk for Legacy Panels: Custom render hooks, views, or Filament-specific features (e.g., statsCard with charts) may need validation post-integration.
• Dependency Conflicts: Compatible with Laravel 11/12/13, PHP 8.2+, Livewire 4.0+, and Flux 2.14+. Tailwind v4 is required for automatic Flux CSS pickup.
• Build Process: Requires npm run build to inject Flux/Tailwind CSS into theme.css. No runtime JS conflicts if using Filament’s default setup.

Technical Risk

Key Questions

1. Filament Version: Is the project locked to Filament v5? If not, this package is not compatible with v3/v4.
2. Custom UI Components: Does the panel use heavily customized Filament views (e.g., sidebar.item, dropdown)? If so, test overrides thoroughly.
3. Icon Dependencies: Are non-Heroicon icon sets (e.g., Font Awesome, Tabler) used extensively? The HeroiconNormalizer handles most cases, but edge cases may require manual fixes.
4. Pagination Needs: Does the project rely on Filament’s pageOptions dropdown or extremeLinks? If yes, disable the pagination Flux replacement.
5. Modal Workflows: Are there custom modals or action confirmations beyond Filament’s native system? Flux’s free tier lacks <flux:modal>, so these must use Filament’s modals.
6. Theme Customization: Is the panel’s theme.css heavily customized? The plugin patches it idempotently, but conflicts may arise.
7. Scaling Plans: Will the panel support multiple tenants or dynamic themes? The plugin’s theme sync feature handles this well.
8. Third-Party Plugins: Are other Filament plugins in use (e.g., filament-notifications, filament-widgets)? Some components (e.g., statsCard) may need validation.

Integration Approach

Stack Fit

• Primary Stack: Laravel 11/12/13 + Filament v5 + Livewire 4.0+ + PHP 8.2+.
• UI Layer: Replaces Filament’s Tailwind-based components with Flux’s modern primitives while preserving data logic.
• Tooling: Requires Node.js (for npm run build) and Tailwind v4 for CSS processing.
• Dependencies:
  • jeffersongoncalves/filament-flux (core plugin).
  • livewire/flux (UI components).
  • filament/filament (v5.x).

Migration Path

1. Pre-Integration:

   • Audit Filament version (composer.json must target ^5.0).
   • Identify custom views/components that might conflict (e.g., resources/views/filament/*).
   • Note any Filament-specific features used (e.g., pageOptions, extremeLinks).

2. Installation:

   composer require jeffersongoncalves/filament-flux
   php artisan make:filament-theme admin  # If not already created
   php artisan filament-flux:install --panel=admin
   npm run build
   

   • The install command patches theme.css with Flux/Tailwind imports.

3. Configuration:

   • Register the plugin in Panel::make():

     return $panel->plugins([
         FilamentFluxPlugin::make()
             ->useEverywhere()  // Auto-replace all fields
             ->useFluxNavigation(['sidebar' => true, 'topbar' => false])
             ->useFluxComponents(['badge' => true, 'dropdown' => false]),
     ]);
     

   • Opt out problematic fields/components (e.g., select, pagination) if needed.

4. Testing:

   • Unit Tests: Verify Flux fields/actions retain Filament’s API (e.g., FluxInput::make()->email()).
   • UI Tests: Check for visual regressions in:
     • Form fields (e.g., FluxSelect vs. native Select).
     • Navigation (sidebar/topbar).
     • Blade components (e.g., <x-flux::badge>).
   • Edge Cases: Test theme switching, dynamic content, and custom render hooks.

5. Post-Integration:

   • Monitor Filament v5 minor updates for breaking changes.
   • Update filament-flux as needed (follow changelog).

Compatibility

Sequencing

1. Phase 1: Safe Adoption (Low Risk):

   • Enable useEverywhere() for non-critical fields (e.g., input, textarea).
   • Test in a staging environment with real data.
   • Validate form submissions, validation rules, and client-side behavior.

2. Phase 2: UI Overhaul (Moderate Risk):

   • Replace navigation (useFluxNavigation()).
   • Opt in Blade components (e.g., badge, dropdown) incrementally.
   • Test custom render hooks and panel layouts.

3. Phase 3: Full Migration (High Risk):

   • Enable shell override for full Flux sidebar/main layout.
   • Replace remaining Filament components (e.g., pagination, statsCard).
   • Audit icon sets and theme customizations.

4. Phase 4: Optimization:

   • Fine-tune Flux