Filament Spotlight 2 Laravel Package

Getting Started

Filament Spotlight 2 is a Filament v3 plugin that adds a Spotlight-style (⌘K / Ctrl+K) command palette for searching resources, pages, and custom actions across your admin panel.

1. Install via Composer:

   composer require jeremykenedy/filament-spotlight-2
   

2. Publish the config and front-end assets:

   php artisan vendor:publish --tag="filament-spotlight-2-config"
   php artisan vendor:publish --tag="filament-spotlight-2-assets"
   

3. Register the plugin on your Filament panel (usually app/Providers/Filament/AdminPanelProvider.php):

   use JeremyKenedy\FilamentSpotlight\SpotlightPlugin;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(SpotlightPlugin::make());
   }
   

4. Clear caches and hard-reload the admin panel. Press ⌘K (macOS) or Ctrl+K (Windows/Linux) — the spotlight modal should open.

First use case: Enable the plugin on your admin panel and confirm the default resource search works. Add a custom action to the palette (see Implementation Patterns) once the baseline is working.

Note on v2.0.1: This release contains only Dependabot dependency bumps (webpack, postcss, axios, json5, browserify-sign, etc.). There are no API, config, or behavioural changes — no migration steps are required when coming from v2.0.0.

Implementation Patterns

Panel-scoped registration. Register the plugin only on the panels that need it, rather than globally, so the ⌘K binding stays predictable:

->plugin(SpotlightPlugin::make())

Custom search sources. The palette is only useful when it surfaces your domain objects. Add actions/closures that resolve to resource URLs, filtering by the current user's permissions:

SpotlightPlugin::make()
    ->actions([
        SpotlightAction::make('Create invoice')
            ->url(InvoiceResource::getUrl('create'))
            ->visible(fn () => auth()->user()->can('create', Invoice::class)),
    ]);

Scoping visibility by role. Because the palette can expose every resource, gate items with ->visible() or an authorize()-style closure. A tenant-aware or role-aware scope here is the difference between a helpful launcher and a security footgun.

Reusing existing Filament search. Let the plugin delegate to Filament's global search rather than duplicating query logic; keep resource-level getGloballySearchableAttributes() meaningful, then let Spotlight render the results.

Keyboard and UX tuning. Configure the keyboard shortcut, modal width/placement, and whether to include pages, resources, or custom actions in the published config file. This is the primary place integrators customise behaviour:

// config/filament-spotlight-2.php
return [
    'keybinding' => ['k'],
    // ... visibility toggles, resources, pages
];

Theming. Style the palette from the panel's theme CSS to match your brand; the plugin ships Tailwind-based markup that responds to Filament's dark-mode classes.

CI/deployment pattern. Include both the config publish and asset publish in your deploy script (or commit the published assets) so new releases don't ship with stale compiled assets — see Gotchas.

Gotchas and Tips

• Assets must be re-published on upgrade. v2.0.1 bumps webpack (5.70 → 5.90), postcss, axios, and related build dependencies. If you vendor the compiled JS/CSS rather than publishing, rebuild and re-publish; otherwise the panel may load stale bundles or throw a 404 on the plugin's asset path after deploy. Run php artisan filament:assets and php artisan vendor:publish --tag="filament-spotlight-2-assets" --force if needed.

• This release is dependency-only. v2.0.1 is entirely Dependabot housekeeping — no new features, no deprecations, no breaking changes. Treat it as a routine security/maintenance bump; the main value is patched transitive npm dependencies (browserify-sign, json5, loader-utils, ip, async, @babel/traverse) that only matter if you rebuild the plugin's assets. If you consume prebuilt assets, there is effectively nothing to do.

• Filament version lock. Spotlight 2 targets Filament v3. Installing it alongside a v2 panel will silently fail to render, or the plugin registration will throw. Confirm filament/filament: ^3.0 in composer.json before debugging anything else.

• Keyboard shortcut conflicts. ⌘K can collide with browser shortcuts (address bar in some browsers) or other JS on the page. If the palette doesn't open, test the shortcut in the panel's dev console to confirm the keydown listener is registered, then change the keybinding in config.

• Empty results / missing items. If the palette opens but shows nothing, the usual causes are: resource not marked globallySearchable, the visible() closure returning false for the current user, or a stale config cache. Run php artisan config:clear and php artisan optimize:clear.

• Cache after config changes. Filament caches components; after changing the plugin config or SpotlightPlugin closures, run php artisan filament:optimize-clear (or optimize:clear) or the changes won't be reflected.

• Extension points. The plugin's action registration and visibility closures are the intended extension surface. Avoid forking the package for small customisations — prefer publishing the config and registering custom actions; that keeps future upgrades (like this one) friction-free.

• Debugging tip. When a search fails, reproduce it against the resource's getGlobalSearchResultUrl() and getGloballySearchableAttributes() directly. The plugin is usually a thin wrapper; problems almost always originate in the resource's global-search configuration.