Nova Theming Classes Laravel Package

Getting Started

• Install with composer require formfeed-uk/nova-theming-classes. Nova packages of this type are auto-discovered via the extra.nova entry in composer.json, so no manual provider registration is normally required.
• After installing, run php artisan nova:publish and clear caches (php artisan optimize:clear) before expecting any visible change — the package works by injecting classes at runtime, so a stale asset/manifest will make it look like nothing happened.
• Where to look first: open Nova in the browser, inspect a first-party component (resource index table, detail form, cards, modals, nav) in devtools, and check the DevTools Elements panel for the injected theming classes. That tells you the naming convention you'll be targeting.
• First use case: write a CSS override against one component type in resources/css/nova.css (or your custom theme's stylesheet) using the injected class instead of brittle structural selectors — e.g. targeting a resource table without relying on div[dusk="..."] attribute selectors or nth-child chains.
• Minimal happy path: install → publish/clear → inspect a component → add one rule keyed off the theming class → npm run dev (or npm run prod) for your theme build.

Implementation Patterns

• Class-based theming over structural selectors. The whole value of this package is letting you write .theming-<component> { ... } instead of #nova .card > div:nth-child(2). Prefer these hooks in your theme; they survive Nova minor UI churn far better than DOM-shape selectors.
• Keep overrides in your own theme layer. Put rules in your Nova custom theme CSS rather than editing vendor assets, so composer update never clobbers your work.
• Scope with a host selector. Because classes are applied to every matching component instance, scope rules under a page/container selector (or a resource-specific dusk attribute) when you only want to restyle one screen.
• CSS variables bridge. A robust pattern is to have the theming classes only set custom properties (--card-radius, --panel-bg) and have your broader stylesheet consume them. This keeps specificity low and overrides composable.
• Pair with Nova's own theming. Use these classes for structural/component-level tweaks and leave brand colours to nova:brand/brandColors() so you aren't fighting Nova's own variable pipeline.
• For custom tools/cards you author, don't depend on this package to style them — style your own components directly and use this package only for Nova's first-party UI.
• Regression-check after every Nova upgrade. Re-inspect the components you restyle after bumping Nova; the package re-applies classes, but the internal markup your rules land on can still change.

Gotchas and Tips

• 1.1.0 is a behaviour change in when classes are applied. The fix moves application to the update lifecycle hook so first-party components registered before liftOff get classes once mounted. If you previously worked around missing classes on early-mounted components (e.g. with MutationObserver shims, setTimeout hacks, or !important rules keyed on late-arriving classes), remove those workarounds and re-verify — they may now double-apply or mask real issues.
• CSS may flash before classes land. Classes are attached client-side after mount/update, so there's a window where your theming selectors don't match. Avoid layouts that collapse without the class; use sensible base styles and treat the theming class as an enhancement, not a load-bearing requirement.
• No classes on third-party components. If a community card/tool renders outside Nova's first-party component set, expect no theming class and style it yourself.
• Specificity surprises. Injected classes are single class selectors — anything Nova ships with higher specificity (or inline styles) will still win. Escalate deliberately rather than blanket-!important.
• Debugging checklist: confirm the package is actually loaded (php artisan about / provider list), confirm the asset build includes your CSS, then inspect for the class before assuming your selector is wrong. If classes are missing on a specific component, that's the package's coverage gap, not your CSS.
• The 1.1.0 dependency bump (loader-utils 1.4.0 → 1.4.1) is build-tooling only. It affects the package's own JS build, not your runtime; no action needed on your side beyond a normal composer update.
• Cache aggressively bites. After upgrading to 1.1.0, clear compiled views, config, and the Nova asset manifest; stale caches are the most common reason a lifecycle-hook fix appears not to have taken effect.
• No public extension points are documented for adding classes to your own components — treat the injected class names as the contract and pin the major version if your theme depends on them.