Nova Essentials Laravel Package

Getting Started

1. Install the package with Composer alongside Laravel Nova (Nova itself is a private package, so your composer.json must already have a Nova repository configured):

   composer require jameslkingsley/nova-essentials
   

   Laravel's package auto-discovery should register the service provider. If it doesn't, add the provider manually in config/app.php (Laravel <5.5) or in bootstrap/providers.php.

2. Read the service provider first — not the README. Open src/*ServiceProvider.php in the package. Every macro this package adds is registered there with Field::macro(...), Metric::macro(...), or Nova::macro(...), usually as one-line closures. That file is the real documentation; the README is often stale and the macro list can drift between versions.

3. Check version compatibility before relying on it. This is a small, low-star package (score 0, no dependents), so confirm the composer.json of the package declares support for your Nova major version (Nova 3/4/5 have breaking changes in the Field API). Pin the version in composer.json rather than floating on dev-main.

4. Verify one macro end-to-end before adopting the rest. Pick a simple field macro you see in the provider, use it in a throwaway Resource, and load the index/detail page. If that works, the rest are likely safe; if it fails, you've saved yourself from sprinkling it across 20 resources.

5. First real use case: use a macro to shorten a field definition you repeat constantly — e.g. a configured date field, a boolean with a label, or a metrics card — and compare the before/after in a single Resource's fields() method.

Implementation Patterns

Treat macros as sugar, not architecture. These are convenience wrappers around Nova's fluent field API. The right pattern is: leave Nova's built-in fluent calls for one-off fields, and only reach for a macro when the same chain appears three or more times across your app/Nova directory.

Wrap macro registration in your own provider. If you adopt several macros, don't scatter them; create App\Providers\NovaMacrosServiceProvider and register your own macros there alongside calls that rely on this package. This gives you one place to remove the dependency later if the package goes unmaintained:

public function boot(): void
{
    // Project-specific macros live here, one layer above the package
    Nova::sortableNavigation();
}

Compose, don't replace. The macros return the same Field/Metric instance, so they should chain with Nova's built-ins:

public function fields(Request $request)
{
    return [
        // Package macro for the base field, then native Nova modifiers on top
        SomeEssentialField::make('published_at')
            ->sortable()
            ->rules('nullable', 'date'),
    ];
}

If a macro returns something that doesn't allow further chaining, that's a red flag — it means it's constructing a field for you rather than configuring one.

Metrics are the highest-value target. Macro packages usually shine on Metric because metric configuration is verbose and repetitive (->ranges(), ->cacheFor(), ->width('1/3')). If this package provides metric helpers, put them in a shared trait or base metric class so every dashboard card is consistent.

IDE support. Nova macros are invisible to static analysis. Add _ide_helper.php stubs or @method docblocks in a base Resource class if you find yourself forgetting the signature — otherwise you'll be reading the service provider on every use.

Test the surface you depend on. Write one feature test that hits a Nova index route (/nova-api/users) for each Resource using a macro. Nova routes are easy to test with actingAs() and a Nova::actingAs()-style helper; this catches the case where a Nova upgrade silently breaks a macro's closure.

Gotchas and Tips

• Macro name collisions are the top risk. Nova registers many macros itself, and so do other packages (nova-* ecosystem is crowded). If two packages register Field::date, whichever provider boots last wins, silently. Grep your vendor/ for ::macro('name' before adding a new dependency that might overlap.

• Service provider boot order matters. Macros only exist when the class method is called. If you call a macro from inside another provider's boot() that runs earlier, you'll get BadMethodCallException. Register this package's provider (or your wrapper) before anything that consumes the macros — auto-discovery order is not guaranteed.

• Closures are bound to the class. Inside a macro, $this refers to the Field (or Metric) instance, not your provider. Copy-pasting a macro body out of the provider into application code without adjusting $this will fail in confusing ways.

• No config to publish (typically). These micro-packages usually ship zero config and zero migrations. If php artisan vendor:publish shows nothing for this vendor, don't fight it — there's nothing to configure. Verify by listing the package directory; if there's no config/, there's nothing.

• Unmaintained-package risk. With no stars and no dependents, expect stale Nova compatibility. Before a Nova major upgrade, either run your macro feature tests or vendor the two or three macros you actually use into your own provider — a 20-line copy is often cheaper than waiting for a fix.

• Debugging: dump the registered macros. There is no built-in "list macros" command, but you can reflect:

  $ref = new \ReflectionClass(\Laravel\Nova\Fields\Field::class);
  dump(array_keys($ref->getStaticProperties()['macros'] ?? []));
  

  (Property name varies by Laravel version — macros on Macroable.) This tells you exactly which macros are live in the current boot cycle.

• Caching doesn't apply. Macros are registered at runtime, so config:cache/route:cache won't affect them — but php artisan optimize in deployment is a good way to confirm nothing else breaks. Don't expect macro registration to be precompiled.

• Extension point to prefer: instead of patching the package, subclass the relevant Nova Field and apply the macro there. That way a package update can't silently change behavior across every Resource you own.