Shoplab Filament Theme Laravel Package

Getting Started

• Install with Composer: composer require shoplab/shoplab-filament-theme.
• v1.0.1 ships pre-built CSS at dist/index.css, so you no longer need to clone the package, run npm install, or build a custom Filament theme just to get the base look.
• Check the package README for the exact Filament panel registration API, then register the theme in your PanelProvider using the documented ->theme(...) / ->viteTheme(...) approach. If the package publishes assets, run the documented vendor:publish command.
• First use case: apply a ShopLab-branded theme to a Filament admin panel in a fresh Laravel app, then verify the panel loads the CSS from the shipped dist/index.css rather than from a locally compiled Vite theme.
• After registering, run the usual Filament cache refresh commands (php artisan filament:assets, php artisan optimize:clear) and load /admin.

Implementation Patterns

• Drop-in panel theme: Register the package theme in each Filament panel that should use it. This is useful when you want a consistent admin UI without maintaining a custom Tailwind/Vite theme pipeline.
• Per-panel branding: In multi-panel apps, apply the theme only to the panels that need it (for example, admin but not a customer-facing panel), or pair it with panel-specific primaryColor() and brand settings.
• Upgrade from v1.0.0: If you previously built the theme from source, switch to the shipped dist/index.css and remove any package-specific build steps from CI. Keep your own app asset build if you still customize Filament CSS.
• Layered customization: Treat the package CSS as a base layer. Put app-specific overrides in a separate CSS file loaded after the theme, or create a small local Filament theme that imports the package styles and adds your own classes.
• Deployment workflow: Since the theme CSS is pre-built, production deploys no longer need Node just for this package. Run Composer install, publish assets if required, and clear Filament/Laravel caches. Keep npm steps only for your own frontend assets.
• Integration with existing Filament themes: If your app already has a custom Filament theme, import or reference the package dist/index.css from that theme rather than registering two competing themes. This keeps Tailwind layers and overrides predictable.

Gotchas and Tips

• Do not edit files under vendor/. Changes to the shipped dist/index.css will be lost on composer update. Put overrides in your app’s CSS or a local theme.
• Asset publishing can overwrite customizations. If the package publishes its CSS into public/, re-publishing after an update may replace edited files. Prefer overriding in app CSS, or track published changes carefully.
• Clear caches after upgrading. Filament caches assets and Blade components. If the new CSS does not appear, run php artisan filament:assets, php artisan optimize:clear, and hard-refresh the browser.
• Check the actual CSS path in the rendered HTML. The most common issue after v1.0.1 is registering a Vite theme path that still expects a build manifest. Inspect the panel source and confirm it points at the package’s shipped CSS.
• Tailwind content scanning still matters for overrides. If you add custom Filament views or classes, your own Tailwind build must scan those paths. The package’s pre-built CSS will not include your app-specific utility classes.
• Watch Filament version compatibility. Theme packages are tightly coupled to Filament’s CSS variables and markup. Confirm the package supports your Filament major version before relying on it across upgrades.
• Dark mode and brand colors may need panel config. If colors look wrong, check Filament’s primaryColor() / brand settings and any dark-mode configuration before overriding CSS.
• Pre-built CSS lowers the barrier but reduces source-level customization. For deep changes, use the package as a base and create a local Filament theme that imports it, rather than fighting the distributed file.