Modules Laravel Package

Technical Evaluation

What the package actually is. coolsam/modules is a thin adapter layer: it wraps nwidart/laravel-modules and exposes each module as a Filament Plugin, with a single ModulesPlugin registered in a panel performing bulk discovery of module resources, pages, widgets, clusters, and nested panels. It is not a module system of its own — it inherits nwidart's runtime, config, and directory conventions, and inherits Filament's plugin/panel registration model.

Architecture fit. Good fit only if modular monolith organization is already a decided requirement. The package's value proposition is code reuse across projects and panel isolation per module; both are architectural commitments, not conveniences. Teams that merely want tidier app/Filament folders should not take this on — they'd be adopting two coupled frameworks (nwidart + Filament plugin lifecycle) to solve a directory problem. Where it fits well: multi-brand or multi-tenant admin suites, agency/white-label reuse, and large panels where one-cluster-per-domain gives the IA for free.

Integration feasibility. Low write-cost, moderate read-cost. The install surface is small — composer require, modules:install, add ->plugin(ModulesPlugin::make()) — but it is a second-order dependency: nwidart must be installed, configured, and autoloaded via Composer's merge-plugin before the wrapper does anything. That autoload requirement is the real integration risk; it changes how composer install behaves in CI and in production images, not just what's in vendor/.

Technical risk.

1. Version treadmill. The support matrix binds package major → Laravel major → Filament major → laravel-modules major (v5.x = Laravel 11–13, Filament 4–5, laravel-modules 11–13). Each framework upgrade therefore becomes a coordinated three-way upgrade with a fourth party (this package) as gatekeeper. The pinning of nwidart's major to the Laravel major at install time is helpful, but it means a Laravel bump can force a nwidart bump and a Filament compatibility check in the same change window.
2. WIP surfaces in security-adjacent areas. Widgets, themes, and — most importantly — access control are marked WIP. The documented access-control approach is to substitute Coolsam\Modules\Resource/Page/*Widget base classes or mix in CanAccessTrait. Swapping base classes as a security control is fragile: any resource that still extends Filament's base class silently lacks the protection, with no compile-time or startup signal. For an admin panel, that is the highest-severity item in this evaluation.
3. Implicit registration. auto-register-plugins plus mode: plugins|panels|both means resources can appear or disappear from navigation based on config and discovery rather than explicit provider registration. Failures skew toward silent omission, not loud errors.
4. Adoption signal is thin. 212 stars and 0 Packagist dependents. Caveat: the dependents count only reflects published packages depending on it, so it undercounts real applications — but it is directionally consistent with a single-maintainer, low-field-validation project. Maturity is "readme, changelog, releases" — no evidence of long-lived production deployments at scale.
5. Bus factor of one. MIT license and a small API mean fork cost is genuinely low, which materially offsets this — but only if you decide that up front rather than during an incident.

Key questions to resolve before committing.

• Is cross-project reuse of admin modules a real roadmap item, or a hypothetical? If hypothetical, the ROI is negative.
• Which mode do we need — plugins, panels, or both? Panel-per-module multiplies navigation, auth, and theming surface; plugins only is dramatically cheaper.
• What is our access-control posture? Can we accept a WIP mechanism in the admin panel, or must we enforce authorization independently of the package (policies + canAccess + Shield/permission integration)?
• Who owns the framework upgrade cadence, and are we willing to fork/patch if the maintainer lags a Filament major?
• Does our deployment pipeline tolerate Composer merge-plugin autoloading of Modules/*/composer.json, including in optimized/--no-dev builds?
• Do modules need independent test suites, CI jobs, and release versioning, or are they just folders in one repo?

Integration Approach

Stack fit. Assume Laravel 12 + Filament 4 as the target, not the newest cells of the matrix. The package supports Laravel 13 / Filament 5, but landing a pilot on the trailing edge of both the framework and the wrapper's newest supported range maximizes the number of moving parts simultaneously in flux. PHP 8.3 minimum is uncontroversial. If the app already uses spatie/laravel-permission and Filament Shield, verify interaction with module-scoped policies before enabling panels mode — that combination is the least documented.

Migration path.

Stop at any phase whose benefit doesn't materialize. Phase 1 is the cheapest place to discover the architecture isn't worth it; phase 5 is the only phase that validates the package's actual pitch.

Compatibility. Pin exact versions (coolsam/modules, nwidart major, Filament minor) and record the matrix in an ADR. Treat the package's version as part of the framework upgrade checklist, not an incidental dependency. Note that the wrapper deliberately does not override Filament's per-panel discovery model — resources bind to panels via the panel provider's discover*() calls, so per-panel scoping is our responsibility, not the package's, and is where mistakes concentrate.

Sequencing. Front-load the two highest-uncertainty items: Composer autoloading in production builds (phase 1) and access control enforcement (independent of phase, but decided before any module ships to users). Defer panels mode until clusters have proven the IA; it's the option with the most blast radius and the least documentation.

Operational Impact

Maintenance. Budget for community-supported, not vendor-supported. Low fork cost is the mitigation: pin the version, keep a short patch queue, and pre-identify the two or three extension points we'd need to patch for a Filament major (plugin registration, discovery, cluster wiring). A single thin wrapper is a reasonable thing to own — a single thin wrapper nobody has looked at in six months is not. Assign an owner and a quarterly "still current on Filament majors?" review.

Support. GitHub issues, no SLA. Internal runbook must cover: how to add a module, how to debug a resource not appearing, how to verify autoload in a fresh clone, and how to flatten a module back into app/ if we walk away. The README is solid for the happy path and explicitly WIP elsewhere — do not assume WIP sections will be resolved on a schedule that matches ours.

Scaling. Runtime overhead is registration/discovery at boot, which is cacheable — ensure config:cache, route:cache, and Filament's component caching are in place, and measure boot time once module count exceeds roughly a dozen. Team scaling is the bigger constraint: modules encourage ownership boundaries, but only if we also enforce them with CODEOWNERS and per-module CI jobs. Without that, modules become a shared mutable namespace with extra indirection.

Failure modes to instrument.

• Silent non-registration. A module missing, misnamed, or excluded by config simply doesn't appear; navigation changes with no error. Mitigation: a smoke test asserting an expected route/nav item per module.
• Autoload breakage in production. The most likely real incident: merge-plugin behavior differs between local and an optimized --no-dev build, producing class-not-found at boot. Mitigation: build the production image in CI on every PR, not just on release.
• Version drift. Filament or laravel-modules minor bump before the wrapper catches up → boot-time exceptions or partially registered panels. Mitigation: dependency pinning plus a scheduled upgrade lane, never a floating constraint.
• Authorization gaps. Resources extending Filament's base classes bypass the module protection layer with no warning. Mitigation: treat package-level access control as defense-in-depth only; enforce policies at the model/resource level and add a static check or code review checklist for base-class usage.
• IA sprawl. Panels or clusters proliferate, nav becomes a second information architecture to maintain, and users lose the back-link path. Mitigation: cap clusters per panel, defer panels mode.
• Orphaned generated files. Clusters enabled after resources already exist leaves resources outside the cluster directory and silently outside the cluster's registration. Mitigation: decide clusters before generating, not after.

Ramp-up. A Filament-fluent developer is productive in half a day to a day; the commands are self-documenting and the conventions are Filament's. The real ramp cost is conceptual: the team must hold three mental models (Laravel service providers, nwidart modules, Filament plugins/panels) and know which layer resolves a given file. Expect a week of confusion around "where does this resource actually get registered" before it clicks. Write the internal conventions doc in phase 2, while the confusion is fresh.

Verdict for a TPM. Composite score of 25 and opportunity of 27 is consistent with what the artifact shows: a useful, competently built thin adapter with a narrow audience, one maintainer, and unresolved WIP in exactly the areas (access control, widgets, themes) that production admin panels care about. Recommend a time-boxed pilot gated at phase 2, with an explicit decision point on whether cross-project module reuse is real. Do not adopt it as a platform-level dependency on the strength of the README alone, and do not adopt it to solve folder organization.