Light Switch Laravel Package

Technical Evaluation

Architecture Fit

• Targeted Use Case: The package is highly specialized for Filament Panel auth pages, addressing a niche but critical UX need (theme switching for login/registration flows). It aligns well with modern Laravel/Filament applications requiring dark mode or system preference support.
• Component-Based Design: Leverages Filament’s plugin architecture, ensuring modularity and non-intrusive integration. The package extends Filament’s existing theme system rather than replacing it.
• CSS-Driven Theming: Relies on Blade-based CSS sourcing (via @source directive), which is a clean but less conventional approach compared to traditional asset pipelines (e.g., Laravel Mix/Vite). This could introduce build tooling dependencies if not managed carefully.

Integration Feasibility

• Filament Dependency: Hard dependency on Filament Panels (v3.x–5.x). If the application uses Filament Admin or Filament Forms/Tables without Panels, this package is incompatible.
• Custom Theme Requirement: Mandates a custom Filament theme (per Filament docs). This adds pre-integration setup work but ensures consistency.
• Blade View Injection: The package injects auth page views via CSS @source directive, which is unconventional and may require:
  • Customization of Filament’s auth view paths.
  • Potential conflicts if other packages modify auth views.
• JavaScript-Free: Uses pure CSS/Blade for toggling, reducing JS complexity but limiting dynamic features (e.g., localStorage persistence without JS).

Technical Risk

Key Questions

1. Filament Ecosystem Fit:

   • Does the application use Filament Panels? If not, is this a blocker or can we explore alternatives (e.g., custom Blade/JS solution)?
   • Are we on Filament v4.x or v5.x? If not, will we upgrade, or is this package too risky?

2. Theme Strategy:

   • Is a custom Filament theme already in place? If not, what’s the effort to create one?
   • How will we handle CSS conflicts with existing auth page styles?

3. User Experience:

   • Should theme persistence (e.g., localStorage) be added? If so, will we implement this via JS or a separate package?
   • Are there accessibility considerations (e.g., contrast ratios in dark mode)?

4. Maintenance:

   • Who will own updates if Filament breaks compatibility?
   • How will we handle future Filament major versions (e.g., v6.x)?

5. Alternatives:

   • Could we achieve this with Filament’s built-in theme system + custom JS?
   • Are there other packages (e.g., spatie/laravel-dark-mode) that offer broader Laravel support?

Integration Approach

Stack Fit

• Primary Stack: Laravel + Filament Panels (v3.x–5.x).
• Secondary Stack: Applications using Filament Admin or standalone Filament may need workarounds (e.g., manual Blade view overrides).
• Tooling Dependencies:
  • CSS Preprocessing: The @source directive requires a build tool (Laravel Mix, Vite, or Blade’s native support). Test compatibility early.
  • JavaScript: Optional for persistence; can be added later if needed.

Migration Path

1. Pre-Integration Setup:

   • Verify Filament version compatibility.
   • Create a custom Filament theme (if not already done) following Filament’s docs.
   • Backup existing auth views (resources/views/auth/).

2. Installation:

   composer require awcodes/light-switch
   

   • Pin the package version in composer.json:

     "awcodes/light-switch": "^3.0"
     

3. Configuration:

   • Add the @source directive to your custom theme CSS file (e.g., resources/css/filament/app.css):

     @source '../../../../vendor/awcodes/light-switch/resources/**/*.blade.php';
     

   • Publish views (if needed) via:

     php artisan vendor:publish --tag="light-switch.views"
     

4. Testing:

   • Test theme toggling on auth pages (login, register, forgot password).
   • Verify no CSS conflicts with existing styles.
   • Test responsive behavior (mobile/desktop).

5. Post-Integration:

   • Add theme persistence (if required) via JS or a separate package.
   • Document the setup for future developers.

Compatibility

Sequencing

1. Phase 1: Install and configure the package in a staging environment.
2. Phase 2: Test with all auth flows (login, registration, password reset).
3. Phase 3: Add persistence (if needed) and monitor performance.
4. Phase 4: Deploy to production with feature flags for rollback.

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor Filament major versions for compatibility breaks.
  • Update awcodes/light-switch when new versions align with Filament updates.
• Customization Overhead:
  • Changes to auth views may require package overrides (e.g., publishing views).
  • CSS conflicts may need manual resolution in future updates.
• Support:
  • Limited community support (47 stars, no dependents). Issues may require self-resolution or direct outreach to maintainers.

Support

• Troubleshooting:
  • Common issues likely relate to:
    • CSS loading (check @source directive and build tooling).
    • Filament version mismatches (verify compatibility matrix).
    • Auth view overrides (ensure paths are correct).
  • Debugging tip: Use php artisan vendor:publish --tag="light-switch.views" to inspect published views.
• Documentation:
  • Gaps: Lacks detailed setup for custom auth views or JS persistence.
  • Recommendation: Create internal docs with:
    • Step-by-step installation.
    • CSS conflict resolution examples.
    • Screenshots of expected UI.

Scaling

• Performance Impact:
  • Minimal: Pure CSS/Blade with no DB or heavy JS.
  • Potential Bottleneck: If @source directive causes slow Blade compilation, consider publishing views manually.
• Multi-Tenant/Regional Deployments:
  • Theme preferences may need user-specific storage (e.g., users table column).
  • Consider geographic defaults (e.g., dark mode for nighttime users in certain regions).

Failure Modes