Filament Moonlight Theme Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation Run composer require notwonderful/filament-moonlight-theme in your project root. Ensure your project uses Filament 4.0+ and PHP 8.1+.

2. Register the Plugin Add the plugin to your Panel provider (e.g., app/Providers/Filament/AdminPanelProvider.php):

   use notwonderful\FilamentMoonlightTheme\MoonlightTheme;
   
   public function panel(Panel $panel): Panel {
       return $panel
           ->plugin(MoonlightTheme::make());
   }
   

3. Publish & Build Assets Run php artisan filament:assets to compile the theme’s CSS/JS. The theme only activates in dark mode (browser/system preference or manual toggle).

4. Verify Open your Filament panel in dark mode—colors should now reflect the Moonlight palette (soft blues, grays, and purples).

First Use Case: Quick Aesthetic Refresh

• Scenario: You want to reduce eye strain during late-night development or improve accessibility for team members.
• Action:
  • Install the package.
  • Register the plugin (5 minutes).
  • Test in dark mode (browser DevTools → Toggle Device Toolbar → Force Dark Mode).
• Result: Immediate visual refresh with minimal effort.

Implementation Patterns

Core Workflow: Theming Across Projects

1. Consistent Dark Theme

   • Use the same theme across multiple Filament panels by reusing the plugin registration.
   • Example: Register in a shared PanelServiceProvider if managing multiple panels.

2. Customization Hooks

   • Override Colors: Extend the theme by publishing its assets:

     php artisan vendor:publish --tag="filament-moonlight-theme-assets"
     

     Modify the published CSS file (e.g., resources/css/filament/moonlight.css) to tweak colors or add variables.
   • Conditional Loading: Disable the theme for specific users/roles by checking auth in the plugin’s register method:

     MoonlightTheme::make()
         ->canAccess(fn () => Auth::user()->prefers_dark_mode)
     

3. Integration with Filament Features

   • Dark Mode Toggle: Pair with Filament’s built-in dark mode toggle (if using Filament 5+) for user control.
   • Livewire Components: The theme automatically applies to Livewire components rendered in Filament panels.

4. Testing

   • Test in both system dark mode and light mode to ensure the theme doesn’t leak into unintended contexts.
   • Use Chrome’s Lighthouse to audit contrast ratios for accessibility.

Advanced Patterns

1. Dynamic Theme Switching

   • Store user theme preferences in the database and conditionally load the plugin:

     public function panel(Panel $panel): Panel {
         return $panel
             ->plugin(
                 request()->user()->prefers_dark_mode
                     ? MoonlightTheme::make()
                     : new LightThemePlugin()
             );
     }
     

2. Theme for Specific Resources/Pages

   • Use Filament’s plugin method in resource classes to scope the theme:

     public static function getPlugins(): array {
         return [
             MoonlightTheme::make(),
         ];
     }
     

3. CI/CD Considerations

   • Ensure filament:assets runs in your deployment pipeline (e.g., Laravel Forge/Envoyer) to avoid broken assets.

Gotchas and Tips

Pitfalls

1. Asset Compilation

   • Gotcha: Forgetting to run filament:assets after installation will leave the theme unstyled.
   • Fix: Add it to your post-install-cmd in composer.json:

     "scripts": {
         "post-install-cmd": [
             "@php artisan filament:assets"
         ]
     }
     

2. Dark Mode Detection

   • Gotcha: The theme relies on the browser/system dark mode setting. If users don’t enable it, the theme won’t apply.
   • Fix: Add a manual toggle button using Filament’s Settings or a custom widget:

     use notwonderful\FilamentMoonlightTheme\Facades\MoonlightTheme;
     
     // Toggle via a button click
     MoonlightTheme::toggle();
     

3. CSS Conflicts

   • Gotcha: Custom CSS in your Filament panel might override the theme’s styles.
   • Fix: Use higher specificity or scope your custom styles to light mode:

     /* Only apply in light mode */
     @media (prefers-color-scheme: light) {
         .custom-class { ... }
     }
     

4. Filament Version Mismatch

   • Gotcha: The package supports Filament 4.0+ but may break with minor Filament updates.
   • Fix: Monitor the GitHub issues and pin the package version in composer.json if needed:

     "notwonderful/filament-moonlight-theme": "1.0.0"
     

Debugging Tips

1. Inspect Elements

   • Use browser DevTools (F12) to verify the theme’s CSS classes (e.g., .filament-moonlight) are loaded.
   • Check the body tag for data-dark attributes if dark mode isn’t triggering.

2. Asset Paths

   • If styles are missing, verify the published assets are in:

     resources/css/filament/moonlight.css
     public/build/filament/css/filament.css
     

3. Clear Caches

   • Run these commands if the theme isn’t applying:

     php artisan cache:clear
     php artisan view:clear
     php artisan filament:assets
     

Extension Points

1. Custom Color Palette

   • Override the default colors by extending the plugin:

     MoonlightTheme::make()
         ->colors([
             'primary' => '#6c5ce7', // Custom primary color
         ]);
     

2. Add Theme to Filament Settings

   • Integrate a theme selector into Filament’s Settings page:

     use Filament\Settings\SettingsWidget;
     
     public static function getSettingsWidgets(): array {
         return [
             MoonlightTheme::makeSettingsWidget(),
         ];
     }
     

3. Localization

   • The theme includes minimal text (e.g., toggle labels). Extend it by publishing translations:

     php artisan vendor:publish --tag="filament-moonlight-theme-translations"
     

Pro Tips

1. Performance

   • The theme adds minimal overhead (~50KB CSS). For large panels, consider lazy-loading it:

     MoonlightTheme::make()
         ->lazyLoad();
     

2. Accessibility

   • Test with tools like WebAIM Contrast Checker to ensure compliance.
   • Add a prefers-reduced-motion media query to disable animations if needed.

3. Community

   • Contribute to the package by submitting PRs for missing Filament versions or additional color schemes.
   • Star the repo to encourage maintenance (low stars may indicate neglect).