Weave Code
Filament Clusters Laravel Package
guava/filament-clusters
guava/filament-clusters helps organize Filament admin panels by grouping resources, pages, and navigation items into configurable clusters, making large Laravel applications easier to structure and navigate. Define clusters in PHP to keep related tools tidy.
guava/filament-clusters adds structured cluster navigation to Filament panels. It lets you group related resources, pages, and custom screens beneath a shared cluster entry, keeping large admin areas organized and easy to explore.
- Define clusters with labels, icons, and sort order
- Attach Filament resources and pages to clusters
- Cluster-aware navigation, routing, and breadcrumbs
- Simple registration in Filament panel providers
- Follows existing Filament conventions for easy integration
Frequently asked questions about Filament Clusters
- How do I install guava/filament-clusters in a Laravel application?
- Install it with composer require guava/filament-clusters:^1.5 and register your clusters in the Filament panel provider. Each clustered resource or page then gets a static $cluster property. There are no migrations, publishable service providers, or asset builds to manage.
- Which Laravel and Filament versions does guava/filament-clusters support?
- The package targets Laravel 11 and 12 with Filament v3. Release 1.5.0 claims Laravel 12 support, but confirm that composer.json actually widened the laravel/framework and filament/filament constraints before relying on it. A CI-only change would fail at install time.
- How do I attach a Filament resource to a cluster?
- Add a static $cluster property to the resource and place clustered resources under app/Filament/Clusters/{Domain}/Resources. Clusters are registered in your panel provider with a label, icon, and sort order. Filament then handles cluster-aware navigation, routing, and breadcrumbs.
- Does clustering change route names and break existing URLs?
- Yes. Moving a resource into a cluster rewrites its route name, for example filament.admin.resources.invoices.index becomes something like filament.admin.clusters.billing.resources.invoices.index. That can break hardcoded route() calls, seeded ACL permissions, Gate definitions, tests, bookmarks, and external deep links, so treat it as a URL-breaking change with its own release note.
- Does this package group form fields or navigation items?
- The documented feature is navigation and URL clustering: grouping resources, pages, and custom screens under a shared cluster entry, URL prefix, and breadcrumb trail. Some package metadata has described grouping multiple fields visually, which is a different feature, so run a short spike to confirm the actual behavior before committing.
- Does guava/filament-clusters work with route:cache and filament:optimize?
- This has not been verified for the package. Test route:cache and filament:optimize with a clustered resource in staging, because a route:cache failure under clustering is a hard stop rather than a minor workaround. Any package leaning on Filament internals can behave differently once components are cached.
- How is this different from Filament native navigation groups?
- Filament navigation groups mainly organize sidebar items, while this package also adds a URL prefix, routing behavior, breadcrumbs, and a dedicated cluster directory. If you only need sidebar grouping, native navigation groups or Filament core clustering may be enough. Adopting this package alongside native clustering can create a permanent two-convention maintenance tax.
- Is guava/filament-clusters suitable for production or customer-facing panels?
- It is acceptable for internal tooling where a single maintainer, community-only support, zero dependents, and low community traction are tolerable risks. It is not recommended for customer-facing, SLA-bearing, or revenue-critical panels without a fork or support plan. Confirm the route-name diff and caching behavior before rollout.
- How should I migrate an existing Filament panel to clusters safely?
- Capture a baseline with php artisan route:list --path=admin, then pilot one low-traffic domain such as Settings or Support. Ship the reorganization as a URL-breaking release with redirects and updated route() calls, permissions, Gate definitions, and tests. Name an owner for the migration PR so the URL churn does not become an unowned refactor.
- Can I customize cluster labels, icons, and ordering without database changes?
- Yes. Clusters are defined in PHP with labels, icons, and sort order, and the package adds no migrations, config surface, or asset build. Integration is mostly the Composer install, the static $cluster property on resources, and registration in the Filament panel provider.
Weaver
How can I help you explore Laravel packages today?