Getting Started

Install the stable line with Composer: composer require vendor/package:^1.0. Before installing, confirm the package's composer.json allows your app's Filament version (filament/filament:^4.0 or ^5.0).

Publish any package config and assets if the README calls for it:

php artisan vendor:publish --tag="package-config"
php artisan vendor:publish --tag="package-assets"

use Vendor\Package\PackagePlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(PackagePlugin::make());
}

Look first at the package README, config/package.php, the plugin class (src/...Plugin.php), and any published views under resources/views/vendor/package.
First use case: add the package's resource, page, widget, field, or column to an existing panel and verify it renders in both local and production-like environments. Since v1.0.0 is the first stable release for Filament v4 and v5, use it as the baseline for new work rather than pinning to pre-release tags.

Implementation Patterns

Register the plugin per panel instead of globally when you run multiple Filament panels. This keeps navigation, resources, and widgets scoped to the correct audience.
Use the plugin's fluent make() / configuration methods in the panel provider for day-to-day toggles, rather than editing vendor files.
If the package ships resources or pages, extend them in app code only when necessary. Prefer configuration and published views for customization so future ^1.0 updates remain low-friction.
For form/table integrations, add the package's fields and columns alongside native Filament components. Keep validation and authorization rules in your app's form/resource classes, not in the package config.
Publish and version-control only the assets/views you actually override. Re-publish with --force deliberately after upgrades and review the diff.
Cover plugin-backed screens with Livewire/Filament tests. At minimum, assert that the panel boots, the plugin's navigation items appear for authorized users, and the primary resource/page loads.
In multi-tenant or role-based apps, combine the plugin's authorization hooks with Filament policies. Verify that navigation and actions are hidden for users who should not see them.
When moving from pre-release/beta tags to v1.0.0, re-check the panel provider registration, re-publish config, and run the test suite before deploying.

Filament v4 vs v5 compatibility is resolved by Composer. Run composer why-not vendor/package if installation fails, and check the package's Filament constraint before upgrading either side.
After upgrading the package or Filament, clear cached config and re-publish assets:
```
php artisan config:clear
php artisan filament:assets
```
Asset and view publishing is the most common source of "my changes disappeared" issues. Confirm whether the package serves assets from public/vendor/... or via Filament's asset pipeline.
Plugin registration order can matter when multiple plugins add navigation or widgets. If items appear twice, check whether the plugin auto-registers something you also added manually.
Avoid editing files under vendor/. Use published views, config, and the plugin's extension points instead.
For debugging panel boot issues, use php artisan about, check Filament's debug output, and temporarily disable other plugins to isolate conflicts.
Pin to ^1.0 for stability, but read each release note for Filament constraint changes. A package supporting both v4 and v5 may still have behavioural differences between them.
Verify authorization early: a plugin that registers resources/pages can expose navigation before your policies are wired up. Test with a non-admin user.
Keep an eye on config caching in production. If plugin settings seem ignored, confirm the config file is present and run php artisan config:cache after changes.