ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
dev-session-1769551498
TenantAtlas/.ai/guidelines/filament-v5-blueprint.md
Ahmed Darrazi 9870f5d102 chore: install Laravel Boost + MCP config
2026-01-20 23:36:08 +01:00

7.9 KiB
Raw Permalink Blame History

Source of Truth

If any Filament behavior is uncertain, lookup the exact section in:

  • docs/research/filament-v5-notes.md and prefer that over guesses.

SECTION B — FILAMENT V5 BLUEPRINT (EXECUTABLE RULES)

Filament Blueprint (v5)

1) Non-negotiables

  • Filament v5 requires Livewire v4.0+.
  • Laravel 11+: register panel providers in bootstrap/providers.php (never bootstrap/app.php).
  • Global search hard rule: If a Resource should appear in Global Search, it must have an Edit or View page; otherwise it will return no results.
  • Destructive actions must execute via Action::make(...)->action(...) and include ->requiresConfirmation() (no exceptions).
  • Prefer render hooks + CSS hook classes over publishing Filament internal views.

Sources:

2) Directory & naming conventions

  • Default to Filament discovery conventions for Resources/Pages/Widgets unless you adopt modular architecture.
  • Clusters: directory layout is recommended, not mandatory; functional behavior depends on $cluster.

Sources:

3) Panel setup defaults

  • Default to a single /admin panel unless multiple audiences/configs demand multiple panels.
  • Verify provider registration (Laravel 11+: bootstrap/providers.php) when adding a panel.
  • Use path() carefully; treat path('') as a high-risk change requiring route conflict review.
  • Assets policy:
    • Panel-only assets: register via panel config.
    • Shared/plugin assets: register via FilamentAsset::register().
    • Deployment must include php artisan filament:assets.

Sources:

4) Navigation & information architecture

  • Use nav groups + sort order intentionally; apply conditional visibility for clarity, but enforce authorization separately.
  • Use clusters to introduce hierarchy and sub-navigation when sidebar complexity grows.
  • Treat cluster code structure as a recommendation (organizational benefit), not a required rule.
  • User menu:
    • Configure via userMenuItems() with Action objects.
    • Never put destructive actions there without confirmation + authorization.

Sources:

5) Resource patterns

  • Default to Resources for CRUD; use custom pages for non-CRUD tools/workflows.
  • Global search:
    • If a resource is intended for global search: ensure Edit/View page exists.
    • Otherwise disable global search for that resource (don’t “expect it to work”).
    • If global search renders relationship-backed details: eager-load via global search query override.
    • For very large datasets: consider disabling term splitting (only when needed).

Sources:

6) Page lifecycle & query rules

  • Treat relationship-backed rendering in aggregate contexts (global search details, list summaries) as requiring eager loading.
  • Prefer render hooks for layout injection; avoid publishing internal views.

Sources:

7) Infolists vs RelationManagers (decision tree)

  • Interactive CRUD / attach / detach under owner record → RelationManager.
  • Pick existing related record(s) inside owner form → Select / CheckboxList relationship fields.
  • Inline CRUD inside owner form → Repeater.
  • Default performance stance: RelationManagers stay lazy-loaded unless explicit UX justification exists.

Sources:

8) Form patterns (validation, reactivity, state)

  • Default: minimize server-driven reactivity; only use it when schema/visibility/requirements must change server-side.
  • Prefer “on blur” semantics for chatty inputs when using reactive behavior (per docs patterns).
  • Custom field views must obey state binding modifiers.

Sources:

9) Table & action patterns

  • Tables: always define a meaningful empty state (and empty-state actions where appropriate).
  • Actions:
    • Execution actions use ->action(...).
    • Destructive actions add ->requiresConfirmation().
    • Navigation-only actions should use ->url(...).
    • UNVERIFIED: do not assert modal/confirmation behavior for URL-only actions unless verified.

Sources:

10) Authorization & security

  • Enforce panel access in non-local environments as documented.
  • UI visibility is not security; enforce policies/access checks in addition to hiding UI.
  • Bulk operations: explicitly decide between “Any” policy methods vs per-record authorization.

Sources:

11) Notifications & UX feedback

  • Default to explicit success/error notifications for user-triggered mutations that aren’t instantly obvious.
  • Treat polling as a cost; set intervals intentionally where polling is used.

Sources:

12) Performance defaults

  • Heavy assets: prefer on-demand loading (loadedOnRequest() + x-load-css / x-load-js) for heavy dependencies.
  • Styling overrides use CSS hook classes; layout injection uses render hooks; avoid view publishing.

Sources:

13) Testing requirements

  • Test pages/relation managers/widgets as Livewire components.
  • Test actions using Filament’s action testing guidance.
  • Do not mount non-Livewire classes in Livewire tests.

Sources:

14) Forbidden patterns

  • Mixing Filament v3/v4 APIs into v5 code.
  • Any mention of Livewire v3 for Filament v5.
  • Registering panel providers in bootstrap/app.php on Laravel 11+.
  • Destructive actions without ->requiresConfirmation().
  • Shipping heavy assets globally when on-demand loading fits.
  • Publishing Filament internal views as a default customization technique.

Sources:

15) Agent output contract

For any implementation request, the agent must explicitly state:

  1. Livewire v4.0+ compliance.
  2. Provider registration location (Laravel 11+: bootstrap/providers.php).
  3. For each globally searchable resource: whether it has Edit/View page (or global search is disabled).
  4. Which actions are destructive and how confirmation + authorization is handled.
  5. Asset strategy: global vs on-demand and where filament:assets runs in deploy.
  6. Testing plan: which pages/widgets/relation managers/actions are covered.

Sources: