Filament Navigation Laravel Package

Technical Evaluation

Architecture fit. van-ons/filament-navigation is a deliberately narrow package: it registers a Navigation Filament resource with a drag-and-drop tree editor, persists menus in a package-owned table, and leaves retrieval/rendering to the host application. For a Laravel app that already runs Filament v4 for its admin surface, this is close to a zero-architecture-change addition — no routing layer, no template engine, no content-model abstraction, no opinion about our frontend. The blast radius is confined to (a) one migration, (b) published frontend assets, (c) one Blade partial we own.

The caveat a TPM must price explicitly: this package solves authoring, not rendering. It gives editors a menu builder and gives us a structured tree; recursive rendering, active-state detection, URL resolution, caching, and cache invalidation are all ours. That is a feature (no frontend lock-in) and a cost (we own the visible output and its bugs). It should be budgeted as the latter.

Integration feasibility. Low. The documented path is three commands (composer require van-ons/filament-navigation:^2.0, php artisan migrate, php artisan filament:assets) plus one ->plugin(FilamentNavigation::make()) line in a panel provider. No service-provider configuration of consequence, no queues, no scheduled jobs, no external service, no credential handling. A single engineer can validate it in an afternoon against a throwaway panel.

Technical risk. The risk is not code quality — it is supply-chain continuity and hard version coupling:

1. Fork lineage. This is a community continuation of ryangjchandler/filament-navigation, discontinued upstream in August 2025. Van Ons (a Dutch agency) has kept the original author's credit and split the line: v1 for Filament ≤v3, v2 for Filament v4+. That is a responsible fork, but continuity now rests on one agency rather than a foundation-backed project.
2. Thin adoption signal. 10 stars, 0 dependents, a single-digit contributor pool, and a changelog dominated by Dependabot and Tailwind/PostCSS bumps. The code surface is small enough that low adoption isn't disqualifying, but it means we will be among the first to hit edge cases — nested reorder bugs, permission gaps on the resource, Filament minor-version breakage.
3. Major-version hard coupling to Filament. v2 dropped v3 support rather than spanning both. When Filament ships v5, expect a coordinated major bump here, and the migration path will be a constraint change plus a rewrite of anything touching the resource — not a graceful deprecation window.
4. JS build-chain surface. The drag-and-drop UI depends on bundled assets (Sortable, Tailwind/PostCSS pipeline) that must be published and re-published on upgrade. Most release noise lives here, which is where breakage will also live.

Mitigating factors: MIT license, full source in vendor/, a plain JSON column, no compiled binary or opaque service. If Van Ons walks away, vendoring or forking is realistic for a package this size. That exit is cheap enough to plan for rather than assume away.

Key questions.

• Which Filament major are our target panels on today? On v4 we take v2; on v3 we are pinned to the v1 line, which is maintenance-only.
• How many panels get the plugin? Registering it everywhere puts a site-chrome editor in contexts where it makes no sense. One admin panel is the sane default.
• Does menu lookup rely on a unique handle (or equivalent) enforced at the database level, or only in the form? Our seeding and template contract both assume lookup returns exactly one record.
• Is there any authorization surface beyond Filament's default policy scaffolding, or must we author a policy so non-admin roles can't rewrite site chrome?
• What Filament/PHP range does composer.json declare, and does the CI matrix actually cover the version we run — or only latest?
• Do we need multi-menu, per-locale, or per-site menus? That determines whether handle proliferation is a schema concern or just conventions.
• What is the tested range in docs/compatibility.md, and does it match our composer.lock?

Integration Approach

Stack fit. Good, and strictly conditional. If Filament v4 is already our admin stack, this is additive. Adopting Filament solely to obtain a menu builder is not justifiable — a hand-rolled CRUD resource is less total weight than a new admin framework plus a plugin. Confirm the Filament dependency first; the rest follows.

Migration path. Two starting states:

• Greenfield (no existing menu package): publish and run the package migration, register the plugin, seed a default menu, wire the render partial. Straightforward.
• Replacing upstream ryangjchandler/filament-navigation: verify the fork's schema matches what we already have on disk before running migrations, then swap the Composer requirement and the namespace/plugin class. Because the fork is lineage-preserving this is usually a composer + use statement change, but the migration must be diffed, not trusted. The v1→v2 jump is separate and is effectively a hard cutover tied to a Filament v4 upgrade — treat it as one project, not two.

Compatibility. Treat version pinning as the primary control: pin the Filament major, pin the package major, and gate upgrades on the package's documented compatibility matrix rather than on ^ resolution. Verify PHP version floor and that our Filament minor is in CI. Record the pinned pair in our dependency policy so a composer update can't silently move us across a breaking boundary.

Sequencing. A defensible order for a TPM to schedule:

1. Spike (0.5 day) — install into a scratch panel, build a nested menu, confirm the editor behaves and the schema lands.
2. Data contract (0.5–1 day) — decide handle naming, uniqueness enforcement, seeding strategy, and the shape our Blade layer will consume.
3. Render partial (1–2 days) — recursive Blade component, active/trail state, external-link handling, accessibility.
4. Caching and invalidation (0.5 day) — menus render on nearly every page; cache the tree and bust on save.
5. Authorization (0.5 day) — policy restricting the resource to admin roles.
6. Rollout (0.5 day) — enable in exactly one panel, deploy with asset publishing in the pipeline.
7. Exit note (0.25 day) — one page documenting how to vendor or fork.

Total realistic first-menu effort: 3–5 engineer-days, of which the package itself is well under one.

Operational Impact

Maintenance. Code maintenance is near-zero; dependency maintenance is the recurring line item. The release history is Dependabot-driven — Tailwind, PostCSS, autoprefixer, Sortable bumps — meaning the JS build chain, not the PHP, is the drift surface. Budget a small recurring allowance to test and bump this package alongside Filament majors. The fork's single-maintainer-agency status means we should be prepared to contribute a patch upstream rather than wait on one.

Support. No vendor SLA. Support is a community GitHub issue tracker plus an agency's goodwill. The realistic escalation path is: read the source in vendor/, patch locally, optionally upstream a PR. That's acceptable for a package of this size, and should be stated plainly to stakeholders rather than implied as "supported."

Scaling. The access pattern is highly asymmetric: menus are read on essentially every page render and written a handful of times per quarter. The table stays tiny; the risk is render-path cost. Cache the resolved tree (per handle, per locale if applicable) and invalidate on save — that reduces the package to a cold-path authoring tool. Asset publishing adds a step to every deploy that touches the package; it belongs in the pipeline, not in a runbook someone remembers.

Failure modes. Ranked by likelihood and blast radius:

• Missed filament:assets on deploy — editor UI breaks silently for admins; frontend still renders. Catch with a smoke check post-deploy.
• Filament minor upgrade breaks the resource — likely given hard major coupling; mitigations are pinning and staging the upgrade with this plugin in scope.
• Corrupted or orphaned tree JSON — a bad nested reorder or a deleted parent leaves dangling nodes; the frontend partial must tolerate malformed trees rather than throwing on render.
• Stale cache after edits — editors save, see no change, file a bug. Invalidation must be part of the initial build, not a follow-up.
• Handle rename breaks templates silently — an editor renames a handle and a section of the site disappears. Enforce immutability of handles in the UI or fail loudly.
• Unauthorized edits to site chrome — no policy means every panel user can restructure navigation. Cheap to fix, expensive to discover late.

Ramp-up. A Laravel developer familiar with Filament is productive on this package in half a day; a developer unfamiliar with Filament carries the framework learning curve, not the plugin's. The genuine ramp-up cost is the rendering partial and access control — that's ordinary application work with no plugin-specific trapdoors — plus a short handover note on version pinning and the fork/vendor exit. Document both, and the package becomes operationally boring, which for a menu builder is the correct outcome.