Filament Shadcn Theme Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require irajul/filament-shadcn-theme
   php artisan vendor:publish --tag=filament-shadcn-theme-config
   

   This auto-discovers the package and publishes the config file.

2. Register the Plugin: Add the plugin to your PanelProvider (e.g., AdminPanelProvider):

   use Irajul\FilamentShadcnTheme\FilamentShadcnThemePlugin;
   
   public function panel(Panel $panel): Panel {
       return $panel->plugin(FilamentShadcnThemePlugin::make());
   }
   

3. First Use Case: Apply a theme preset (e.g., Lyra style with Taupe colors):

   ->plugin(FilamentShadcnThemePlugin::make()
       ->style(StyleVariant::Lyra)
       ->baseColor(BaseColor::Taupe)
       ->themeColor(ThemeColor::Taupe)
   )
   

   Refresh your Filament panel to see the theme applied.

Where to Look First

• Config File: config/filament-shadcn-theme.php for global defaults.
• Panel Provider: Override theme settings per panel.
• Enums: Enums/ directory for available options (e.g., StyleVariant, BaseColor).

Implementation Patterns

Common Workflows

1. Panel-Specific Theming: Override defaults in the PanelProvider for each Filament panel:

   ->plugin(FilamentShadcnThemePlugin::make()
       ->style(StyleVariant::Nova)
       ->font('geist')
   )
   

2. Dark/Light Mode Sync: Use Filament’s ThemeMode with the plugin’s darkMode() helper:

   ->defaultThemeMode(ThemeMode::Dark)
   ->plugin(FilamentShadcnThemePlugin::make()->darkMode(true))
   

3. Production Optimization: Switch to cached-asset mode for performance:

   ->plugin(FilamentShadcnThemePlugin::make()->cssMode(CssMode::CachedAsset))
   

   Warm the cache after deployment:

   php artisan filament-shadcn-theme:cache --panel=admin
   

4. Custom Fonts: Use built-in fonts or custom strings:

   ->font('inter') // Built-in
   ->headingFont('Custom Font, sans-serif') // Custom
   

5. Token Overrides: Fine-tune shadcn tokens directly (e.g., for accessibility):

   ->tokens(
       light: ['background' => 'oklch(1 0 0)'],
       dark: ['background' => 'oklch(0.16 0.01 90)']
   )
   

6. Selector Mapping: Target custom Filament classes (e.g., from plugins):

   ->selectorMap([
       'card' => '.fi-section, .custom-card-class',
   ])
   

Integration Tips

• Filament Plugins: Ensure the plugin is registered after other Filament plugins that might inject CSS (e.g., widgets).
• Multi-Panel Apps: Register the plugin separately for each panel with unique configurations.
• Testing: Use filament-shadcn-theme:clear to reset cached assets during tests:

  php artisan filament-shadcn-theme:clear --panel=admin
  

Gotchas and Tips

Pitfalls

1. CSS Conflicts:

   • Issue: Inline CSS may conflict with other Filament plugins or custom styles.
   • Fix: Use cached-asset mode for isolation or scope selectors tightly (e.g., .filament-shadcn-*).

2. Font Loading:

   • Issue: Custom fonts may not load if not preloaded in the layout.
   • Fix: Add @font-face rules to your app’s CSS or use a CDN (e.g., Google Fonts).

3. Dark Mode Mismatch:

   • Issue: Filament’s ThemeMode and the plugin’s darkMode() may desync.
   • Fix: Explicitly set both:

     ->defaultThemeMode(ThemeMode::Dark)
     ->plugin(FilamentShadcnThemePlugin::make()->darkMode(true))
     

4. Cached Asset Permissions:

   • Issue: cached-asset mode fails if public/vendor/ is unwritable.
   • Fix: Ensure the directory is writable or use storage/framework/ (requires config override).

5. Selector Specificity:

   • Issue: Custom selectors may not override Filament’s default classes.
   • Fix: Inspect the rendered HTML and adjust selectorMap (e.g., target .fi-* classes).

Debugging

• Inspect Tokens: Use browser dev tools to check generated CSS variables (e.g., --fs-primary).
• Clear Cache: Run filament-shadcn-theme:clear if changes don’t apply.
• Log Config: Temporarily log the plugin config to verify settings:

  dd(FilamentShadcnThemePlugin::make()->getConfig());
  

Extension Points

1. Dynamic Themes: Load configurations from a database or API:

   $theme = Theme::find($id);
   ->plugin(FilamentShadcnThemePlugin::make()
       ->style($theme->style)
       ->themeColor($theme->color)
   )
   

2. User Preferences: Store theme preferences in the user model and apply them via middleware:

   // Middleware
   $user->theme->applyTo(FilamentShadcnThemePlugin::make());
   

3. Custom Tokens: Extend the package by publishing and overriding the tokens() method in a child class:

   class CustomShadcnThemePlugin extends FilamentShadcnThemePlugin {
       public function tokens(): array {
           return array_merge(parent::tokens(), [
               'light' => ['--custom-token' => 'value'],
           ]);
       }
   }
   

Config Quirks

• Default Values: The config file merges with fluent settings (fluent overrides config).
• String vs. Enum: Use enums for autocompletion (e.g., StyleVariant::Lyra) or strings (e.g., 'lyra').
• Icon Library: Currently a CSS token; future versions may add icon-specific styling.

Performance

• Inline CSS: Slower initial load but no asset dependencies.
• Cached Asset: Faster subsequent loads but requires disk writes.
• Token Overrides: Minimize overrides to reduce CSS specificity battles.

Testing

• Isolated Tests: The package includes standalone tests; host apps should test integration.
• Theme Switching: Mock the plugin in tests to verify dynamic theming:

  $this->filament->plugin(FilamentShadcnThemePlugin::make()->style('nova'));