Laravel Nova Theme Classify Laravel Package

Technical Evaluation

Architecture fit. The package is a micro-utility, not a theme: it resolves which Nova theme is active and exposes it as a class (typically on body) so CSS and Blade views can scope per theme. Architecturally that is a sound, low-coupling pattern — a config map, a container-bound resolver, a single emission point. The fit question is therefore not "does the design suit our stack" but "do we need theme classification at all." That is gated on a confirmed multi-theme requirement (per-tenant, per-brand, or light/dark). If the admin surface is one stock Nova look, this package supports no roadmap decision and should be recorded as prior art only.

Integration feasibility. Composer-installable, MIT, no heavy build step, auto-discovery plus a publishable config stub. On paper: trivial. In practice, feasibility is entirely determined by version drift. Last release 2019-06-08 places it in the Nova 1.x/2.x era; Nova 4/5 rebuilt the front end on Vue 3/Vite with its own theming conventions. Assume it does not boot on Nova 4/5 or PHP 8.2+ until a disposable-branch spike proves otherwise. Read composer.json constraints and src/ before any install — the source is tens of lines, so a source read is cheaper than a debugging cycle.

Technical risk.

• Dependency risk (high, low probability of value offsetting it): stale constraints can pin or conflict on laravel/nova, Laravel, or PHP, converting a cosmetic helper into a blocker on a platform upgrade.
• Boot risk (medium impact, low effort to mitigate): a provider boot failure takes down the entire admin panel. Isolate to staging with a one-command rollback.
• Silent visual breakage (high, under-monitored): when a theme class stops matching after a Nova update, nothing errors — the admin just looks wrong. Backend monitoring will never catch this.
• Scope risk (documentation): the README sells a drop-in visual theme; the code classifies. Scope must be set from /src, never from marketing copy.
• Ownership risk (structural): 17 stars, 0 dependents, ~6 years without a release means zero ecosystem compatibility pressure. Every future upgrade is our problem alone.

Key questions.

1. Do we have a confirmed multi-theme requirement today, or is this speculative?
2. Which Nova major version and PHP runtime are we pinned to, and has the package been spiked against exactly those?
3. Who is the named internal owner if we vendor or fork it?
4. Is theme resolution server-side (config, session, tenant) or user-toggled client-side? Client-side toggles invalidate the "no JavaScript" benefit.
5. Can we commit admin-UI visual regression checks to the deploy pipeline?
6. Is the outcome better expressed as first-party CSS custom properties or a small custom Nova tool we own end to end?

Recommendation: do not add as a runtime dependency. Reproduce the pattern in-house — config map of theme → classes, resolver bound in the container, resolved once in a Nova::serving callback, emitted as a body class. If a legacy Nova 2 install forces the issue, fork under an internal namespace, pin exact versions, and treat upstream as reference.

Integration Approach

Stack fit. Laravel/Nova is our stack; the package is a Composer package with a service provider and a published config. Mechanically it fits. The meaningful fit test is the Nova major version: Nova 1.x/2.x is native territory for this; Nova 4/5 is not, and the correct integration there is reimplementation against Nova's own theming primitives rather than adaptation of a 2019 artifact.

Migration path. Preferred path is replacement, not adoption: a four-part in-house implementation (config map, container-bound resolver, single Nova::serving resolution, body-class emission in the layout). Budget it as an afternoon of internal engineering, not a vendor evaluation. Fallback path, only for a legacy Nova 2 app with a real multi-theme requirement: fork upstream into an internal namespace with a named owner, keep the published config as the extension surface, and wrap access in our own view helpers (theme_body_class(), theme_class('card')) so a future swap touches one file rather than every Blade view. Do not run both — pick adoption or replacement explicitly.

Compatibility. Two axes. Version compatibility: verified only by a staging spike against our exact Nova, Laravel, and PHP pins; the lockfile must be reviewed, and we should assume conflicts until disproven. Styling compatibility: the classifier must compose with Nova's compiled Tailwind shell, not fight it. Scope rules under the emitted body class, prefer CSS custom properties over duplicating component rules per theme, and avoid specificity escalation — otherwise a Nova minor bump silently degrades the admin. Also confirm coverage: login screens, error pages, and Nova's own layouts may not render the body class, so don't assume global body.theme-*.

Sequencing.

1. Gate (days, not sprints): confirm the multi-theme requirement exists and read /src + composer.json to fix actual scope.
2. Spike (1–2 days): disposable branch, composer require, publish config, verify provider boot and that the class is emitted on the specific page we style. Roll back if anything is ambiguous.
3. Decide: reimplement in-house (default) vs. fork-and-own (legacy exception).
4. Build: config map → resolver → single resolution point → view helpers → scoped CSS with custom properties.
5. Harden before rollout: config:clear in the deploy steps, admin-UI visual regression snapshots, explicit post-deploy Nova smoke check, documented one-command rollback.
6. Extend: point custom cards and tools at the same resolver so body class and component classes cannot diverge — this is the seam that makes per-tenant branding viable later.

The decision cost must not exceed the implementation cost. If step 1 comes back negative, stop with a one-line note in the architecture log.

Operational Impact

Maintenance. This is the decisive cost. Upstream has shipped nothing since June 2019 and has no dependents creating compatibility pressure, which means maintenance transfers entirely to us — either as a forked dependency we now own, or as an in-house file we wrote. The in-house version is strictly cheaper: same maintenance burden, no Composer constraint exposure, no archaeology when something breaks. Under adoption, the recurring work is re-verifying against each Nova and PHP upgrade and re-checking Tailwind shell interactions after every Nova minor.

Support. No upstream support channel of consequence, no security patching, no bug-fix path. Internal support is limited to whoever owns the theme layer. Because the failure mode is visual rather than logged, first-line support (helpdesk, on-call) cannot triage it — expect "the admin looks wrong" tickets routed straight to engineering with no signal to work from. Mitigate by naming an owner and publishing a short runbook: check auto-discovery, check config cache, check whether the page renders the emitting layout.

Scaling. The mechanism scales fine — one resolution per request, one class emission, and CSS variables mean adding a third (tenant/custom) theme is a variable block, not a rule set. Two scaling caveats: (a) per-tenant branding multiplies the number of themes and therefore the visual regression surface, so snapshot coverage must grow with tenant count; (b) if users can toggle themes client-side without a round trip, server-resolved classes go stale — either persist preference server-side (cookie/session/DB) or accept a JS shim, which forfeits the no-JavaScript rationale for adopting this pattern.

Failure modes.

• Hard failure: Composer constraint conflict blocks install or a platform upgrade; provider boot exception takes down the admin panel. Detectable immediately, cheap to roll back if staged.
• Silent failure (the dangerous one): theme class stops matching after a Nova update, or isn't emitted on a given page; admin renders with default styling. No error, no alert. Only visual regression checks or a manual post-deploy smoke check catch it.
• Inconsistency failure: resolution called per component instead of once at serving, producing mismatched classes on the same page.
• Configuration failure: stale cached config makes a correct install look broken. php artisan config:clear resolves; document it as step one of triage.

Ramp-up. Low. The source is tens of lines and the concept is a config map plus a body class — a mid-level Laravel engineer is productive within a day, and the in-house implementation is within reach of anyone comfortable with service providers. The real ramp-up cost is not learning the package; it is building the safety net (visual regression snapshots, rollback command, smoke check) that makes silent theme breakage survivable. Budget that explicitly, because without it the second-order cost of a cosmetic feature quietly exceeds its value.

Bottom line for the roadmap: gate on a confirmed multi-theme requirement; if it exists, ship the in-house implementation and keep this repo as reference prior art; if it doesn't, take no action and close the item.