filament-plugin-development
Skill7 starsChanged 4 months agoMITView on GitHub
Build and publish custom Filament plugins (Filament is the Laravel admin-panel framework). Use when creating a Filament plugin/package, implementing the Plugin contract, scaffolding from the plugin skeleton, registering assets/resources/pages/render-hooks, making a configurable plugin, testing it, or publishing to Packagist and the filamentphp.com/plugins directory. Targets Filament v4 (v5 shares the same plugin API). For USING Filament (resources/forms/tables), use the laravel-filament skill instead.
- Commits and pushes
In this repository9 other files it gives its agents.
- geo-llm-optimizationSkill
- lahjaSkill
- laravel-architecture-reviewSkill
- laravel-filamentSkill
- laravel-mixpostSkill
- laravel-mysql-to-postgresSkill
- laravel-upgradeSkill
- livewireSkill
- skill-authoringSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 71
Only reach for closure config (bool|Closure + the EvaluatesClosures trait's evaluate()) when you actually need closures - don't wrap a …
- Very specific: line 157
Never hardcode panel assumptions (id admin, a path, single-panel) - read the passed Panel.
- Distinctive: line 159
Keep it plain when one component is all you ship.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Building & publishing Filament plugins (v4 / v5)
A Filament "plugin" is just a Composer package that extends a Filament app. Verified against filamentphp.com/docs/4.x. v5 shares the same plugin API.
Two tiers - pick the smaller one
A. Plain package (components only). Ships resources/pages/widgets/fields/actions and does not implement any contract. The installing app wires them in manually (->resources([...]), ->widgets([...])). If your package is one widget or one field, do this - you do not need the Plugin contract.
B. Panel Plugin. A class implementing Filament\Contracts\Plugin, registered with ->plugin(YourPlugin::make()). Reach for this only when you bundle multiple things behind one registration, need per-panel configuration, or need boot-time logic. Rule of thumb: more than one moving part, or configurable -> Plugin contract; otherwise ship it plain.
The Plugin contract
Three methods:
| Method | Runs | Purpose |
getId(): string | - | Globally-unique, stable singleton key (e.g. 'blog' - not 'settings', which clashes) |
register(Panel $panel): void | while the panel is configured | register resources/pages/widgets/render hooks/assets on the panel |
boot(Panel $panel): void | only for the active panel (via middleware) | runtime side effects |
namespace Vendor\FilamentBlog;
use Filament\Contracts\Plugin;
use Filament\Panel;
class BlogPlugin implements Plugin
{
public function getId(): string { return 'blog'; }
public function register(Panel $panel): void
{
$panel->resources([PostResource::class])
->pages([Settings::class])
->widgets([BlogOverviewWidget::class]);
}
public function boot(Panel $panel): void { /* runtime side effects here */ }
public static function make(): static { return app(static::class); } // install-side: ->plugin(BlogPlugin::make())
public static function get(): static { return filament(app(static::class)->getId()); } // read configured instance anywhere
}Register in the app's PanelProvider: ->plugin(BlogPlugin::make()).
#1 v3 -> v4 migration break: boot-time side effects must be in
boot(Panel $panel), NOT the constructor - in v4 the constructor no longer fires them and they silently stop working.
Configurable plugins
Fluent setter returns static; getter reads it; register()/boot() branch on it. Config is per-panel (each ->plugin(Make()->...) call gets its own container-bound instance):
protected bool $hasAuthorResource = false;
public function authorResource(bool $condition = true): static { $this->hasAuthorResource = $condition; return $this; }
public function hasAuthorResource(): bool { return $this->hasAuthorResource; }
public function register(Panel $panel): void
{
if ($this->hasAuthorResource()) { $panel->resources([AuthorResource::class]); }
}Install-side: ->plugin(BlogPlugin::make()->authorResource(true)). Read anywhere: filament('blog')->hasAuthorResource().
Only reach for closure config (bool|Closure + the EvaluatesClosures trait's evaluate()) when you actually need closures - don't wrap a plain bool in closure machinery.
Scaffolding: the official skeleton
There is no make:filament-plugin command. Start from filamentphp/plugin-skeleton:
- "Use this template" -> your repo, clone it.
php ./configure.php- interactive; rewrites stubs (vendor/namespace/author) and deletes itself.- Delete unused boilerplate (
config/,database/,src/Commands/,stubs/) - lazy wins.
Service provider - Spatie Package Tools (v4)
Extend Spatie\LaravelPackageTools\PackageServiceProvider (the v3 PluginServiceProvider is removed; a missing static $name throws):
use Spatie\LaravelPackageTools\{Package, PackageServiceProvider};
use Filament\Support\Facades\FilamentAsset;
use Filament\Support\Assets\AlpineComponent;
use Livewire\Livewire;
class ClockWidgetServiceProvider extends PackageServiceProvider
{
public static string $name = 'clock-widget';
public function configurePackage(Package $package): void
{
$package->name(static::$name)->hasViews()->hasTranslations();
// ->hasMigrations([...]), ->hasConfigFile(), ->hasCommands([...]) as needed
}
public function packageBooted(): void
{
Livewire::component('clock-widget', ClockWidget::class);
FilamentAsset::register(
[ AlpineComponent::make('clock-widget', __DIR__ . '/../resources/dist/clock-widget.js') ],
package: 'vendor/clock-widget',
);
}
}Auto-discovery via composer.json extra.laravel.providers (the skeleton sets this).
Assets
Register in the provider's packageBooted(). Always pass package: to namespace assets into their own /public subdir (prevents filename collisions):
use Filament\Support\Assets\{Css, Js, AlpineComponent};
FilamentAsset::register([
Css::make('my-styles', __DIR__.'/../resources/dist/plugin.css'),
Js::make('my-scripts', __DIR__.'/../resources/dist/plugin.js')->loadedOnRequest(),
AlpineComponent::make('my-widget', __DIR__.'/../resources/dist/my-widget.js'),
], package: 'vendor/package');->loadedOnRequest()/ async Alpine components = loaded only when referenced. Prefer this; don't ship a global CSS/JS that loads on every page for a one-page feature.- Truly-global assets: register on the panel via
$panel->assets([...])inregister(). - Retrieve:
FilamentAsset::getStyleHref('id', package: 'vendor/pkg'),getScriptSrc(...),getAlpineComponentSrc('id','vendor/pkg')(withx-load/x-load-srcin Blade). - Commit built assets (
resources/dist) so consumers don't need your Node toolchain.
Render hooks
Inject Blade at fixed UI points:
use Filament\View\PanelsRenderHook;
// per-panel, in register():
$panel->renderHook(PanelsRenderHook::BODY_START, fn () => view('blog::banner')->render());
// or globally, in the provider (with optional scopes):
\Filament\Support\Facades\FilamentView::registerRenderHook(
PanelsRenderHook::USER_MENU_BEFORE, fn () => view('blog::menu-extra')->render(),
scopes: \App\Filament\Pages\Dashboard::class,
);PanelsRenderHook has constants for BODY_*, TOPBAR_*, SIDEBAR_*, PAGE_*, USER_MENU_*, etc.
Views, translations, testing
->hasViews()namespacesresources/views/x.blade.phpasclock-widget::x(protected static string $view = 'clock-widget::widget';).->hasTranslations()->__('clock-widget::file.key'). Consumers publish overrides with--tag=clock-widget-views(-translations,-config,-migrations).- Test with Pest + Orchestra Testbench (skeleton ships it). Boot a minimal panel with the plugin registered, then Filament's Livewire helpers:
use function Pest\Livewire\livewire;
livewire(ListPosts::class)->assertOk()->assertCanSeeTableRecords(Post::factory()->count(3)->create());Publishing
- Packagist: valid
composer.json(vendor/plugin, PSR-4,extra.laravel.providers, a real"filament/filament": "^4.0"constraint - don't floatdev-main); tag SemVer (git tag v1.0.0 && git push --tags); submit to Packagist + enable the GitHub webhook. Consumerscomposer require vendor/plugin. - Official directory: request author access at filamentphp.com/author (the old GitHub-PR flow is retired - it's the author dashboard now), then submit name/description/docs/repo/categories + support flags (dark mode, i18n, Filament versions). Free or paid listings supported.
Gotchas recap
- Boot-time side effects ->
boot(), not the constructor (v4 break). getId()unique + stable (it's the singleton key).- Namespace assets with
package:; prefer on-request/async loading. - Never hardcode panel assumptions (id
admin, a path, single-panel) - read the passedPanel. - Extend
PackageServiceProviderwith a static$name. - Keep it plain when one component is all you ship.
Sources
Panel plugins · Building a panel plugin · Assets · plugin-skeleton · Author dashboard
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

