Getting Started

Read the repo before you install it. With 2 stars, 0 dependents, and no surrounding blog/Stack Overflow ecosystem, ml-solutions-ltda/nova-dashboard has nobody else to answer your questions. Spend ten minutes in src/ first: service provider → dashboard class → wherever cards get registered. That last file is where you'll live day-to-day.

Step 1 — check the Nova constraint before anything else. Nova's card and metric APIs have changed across v3 → v4 → v5, and Nova is closed-source, so a resolver mismatch is the cheapest possible way to end the evaluation. Look at the package's composer.json against your pinned laravel/nova version:

composer require mlsolutions/nova-dashboard --dry-run

If it resolves, install for real, then confirm auto-discovery picked up the provider:

composer require mlsolutions/nova-dashboard
php artisan vendor:publish   # look for the package's tags/namespace
php artisan route:list | grep -i dashboard

The exact provider namespace and publish tags aren't reliably documented — if vendor:publish lists nothing, open the service provider and read its boot()/publishes() calls directly. Don't guess tag names.

Step 2 — publish and sanity-check assets. A dashboard that renders an empty grey box with 404s in the console is almost always unpublished or unbuilt frontend assets, not a PHP bug. Confirm public/vendor/... exists and hard-refresh before you start debugging card logic.

Step 3 — first use case: your own landing page. Don't replace Nova's stock Main dashboard on day one. Register a second dashboard — an ops or finance view — with two or three cards you already have (active users, revenue this month, queue depth). Load it at its registered URI and confirm it renders. Once that's green, you have a working shell to iterate against, and you've proven the package is compatible with your Nova version.

Step 4 — pull the card list into app code. The single most important move on day one: whatever dashboard class the package ships, subclass it in app/Nova/Dashboards/ (or copy its card list into a project-owned class) so ordering and authorization live in your repo, not vendor/.

namespace App\Nova\Dashboards;

use MlSolutions\NovaDashboard\...\Dashboard as BaseDashboard;

class OpsDashboard extends BaseDashboard
{
    public function cards(): array
    {
        return [
            new \App\Nova\Metrics\ActiveUsers,
            new \App\Nova\Metrics\QueueDepth,
        ];
    }

    public function name(): string
    {
        return 'Operations';
    }
}

Implementation Patterns

Use first-party Nova cards, not package cards. The package's real value is the dashboard shell, layout, and any per-user/per-role assignment it adds. Populate it with Nova's own Value, Trend, Partition, and Progress metrics. That keeps you on documented, supported APIs and means an abandoned package doesn't strand your widgets — you can port the whole dashboard to a plain Nova dashboard class in an afternoon.

Persona-scoped dashboards are the highest-leverage pattern. Build one dashboard per role — ops, finance, account management — and gate at both levels:

// dashboard-level
public function authorizedToSee(Request $request)
{
    return $request->user()->hasRole('finance');
}

// card-level, for mixed dashboards
(new RevenueThisMonth)->canSee(fn ($request) => $request->user()->hasRole('finance')),

This is the day-to-day win: a support agent opens Nova and sees queue depth and ticket SLA, not revenue. It also doesn't depend on package internals, which matters given the adoption risk.

Make metrics cheap — cache the calculate(). The dashboard is the most-hit page in most Nova installs and the easiest place to accidentally fire five heavy aggregates per request. Wrap expensive queries:

public function calculate(NovaRequest $request)
{
    $key = sprintf('metric:revenue:%s:%s', $request->user()->tenant_id, $request->range);

    return $this->result(
        Cache::remember($key, now()->addMinutes(5), fn () => /* aggregate */)
    );
}

Key by range and tenant or you'll leak one tenant's numbers into another's cache. This is the number-one production gotcha in a multi-tenant Nova.

Wire clicks through to filtered resource indexes. A dashboard that dead-ends is a dashboard people stop opening. Use Nova's linkTo/url on partition and trend cards so a click lands on /nova/resources/users?viaResource=... or a pre-filtered index. This is what turns the dashboard from a widget into a workflow.

Per-user layout, if the package persists it. If the package stores card ordering/visibility, back it with your own migration for a preferences table and hydrate in the dashboard class rather than relying on undocumented internals. Wrap this abstraction early — it's the most likely thing to break on a package or Nova upgrade.

Write two feature tests and be done. With a package this thin, your tests are the regression net across Nova minor bumps:

public function test_ops_dashboard_requires_role()
{
    $this->actingAs(User::factory()->create())
        ->get('/nova/dashboards/ops')
        ->assertForbidden();

    $this->actingAs(User::factory()->ops()->create())
        ->get('/nova/dashboards/ops')
        ->assertOk();
}

Re-run these on every Nova or PHP bump, and manually load each card. With zero upstream dependents, you are the integration test.

Gotchas and Tips

Adoption risk is the headline. Two stars, zero dependents, single-maintainer cadence. Treat it as pinned infrastructure: exact-version constraint in composer.json, lock file committed, and a decision made up front about whether you'd fork. MIT licensing makes vendoring the dashboard class into app/Nova/Dashboards/ entirely viable — do that if maintenance stalls, and keep the package out of your critical path.

Nova version drift produces misleading errors. If you hit Call to undefined method on a card or a Call to a member function on a metric response, suspect a Nova major mismatch before you suspect the package. Check the package's declared constraint and its last release date against your Nova major.

Asset failures are silent. Missing manifests show up as a blank dashboard area with console 404s — no PHP exception, no log entry. After install (and after any deploy), verify public/vendor/... exists, run the package's npm run build if it ships sources, and hard-refresh. Stale browser cache on Nova assets is a recurring "nothing changed" trap.

Route and dashboard-name collisions. If the package registers a dashboard named main, or a route that overlaps Nova's, you can shadow the default dashboard or get a 404. Inspect Nova::dashboards() output and the provider's route registration. Prefer namespaced names (ops, finance) over anything resembling main.

Published config carries stale defaults. Config files from thin packages frequently reference card classes that no longer exist. Diff the published config against the package's own config/ and always run:

php artisan config:clear
php artisan route:clear

after editing. Nova + config caching is the classic "my change did nothing."

Audit authorization defaults before shipping. Verify whether the dashboard and its cards default to open or gated — a thin package may have canSee returning true. In an admin panel that renders arbitrary metrics per user, a gap here is a data-exposure bug, not a cosmetic one. Check the behaviour under your multi-tenancy model explicitly.

Debug in this order: (1) is the provider loaded (php artisan about), (2) do routes exist (route:list | grep -i dashboard), (3) do assets resolve (browser console), (4) do the card classes exist and return data, (5) authorization. Ninety percent of issues are steps 1–3.

Where to extend, not edit. Subclass the dashboard class, register your own cards, and hook Nova::serving() for any global configuration. Never edit files under vendor/ — the next composer update erases them, and with this package's release cadence that update may be your last chance to take a fix.

Upgrade checklist. On any Nova or PHP bump: composer update --dry-run to see whether the constraint still resolves, run the dashboard feature test, then manually load every card in the browser. If the constraint blocks the Nova upgrade, that's your trigger to vendor the dashboard class and cut the dependency.

Nova Dashboard Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips