Nova Charts Laravel Package

Getting Started

vemcogroup/nova-charts 4.0 is a Laravel 9 compatibility release. Treat it as a platform-upgrade release first, not a feature release: the visible change is Laravel 9 support, so the first job is confirming your app and Nova versions line up.

Start here:

1. Check the package’s composer.json constraints on GitHub/Packagist before upgrading. Confirm which Laravel and Nova versions 4.0 requires.
2. If you are still on Laravel 8 or an older Nova line, stay on 3.0.4 until the app is upgraded.
3. Install/upgrade with an explicit constraint:

composer require vemcogroup/nova-charts:^4.0

4. Clear Laravel and Nova caches, then publish any package config/assets exactly as documented by the package README:

php artisan optimize:clear
php artisan vendor:publish --tag=nova-charts-config
php artisan vendor:publish --tag=nova-charts-assets

Tag names can vary by package version; use the tags listed by the installed package rather than guessing.

First practical use case: add a chart card to a Nova dashboard or resource. Register the card in NovaServiceProvider::cards() for a global dashboard card, or in a resource’s cards() method for a resource-specific chart. Start with one low-risk chart such as “new users per day” or “orders by status”, confirm the data shape renders correctly, then expand.

Implementation Patterns

Use Nova chart cards as presentation components and keep data retrieval in dedicated classes or services. This keeps dashboard cards testable and avoids burying complex queries in cards().

Common day-to-day patterns:

• Dashboard cards: register chart cards globally in NovaServiceProvider::cards() when the metric is relevant across the admin.
• Resource cards: register charts in a resource’s cards() method when the chart depends on that resource’s domain, policies, or filters.
• Query objects: put aggregation logic in a small class such as SignupsByDayChartData rather than a large closure. Return a stable array/collection shape expected by the chart card.
• Aggregate in the database: use selectRaw, groupBy, and date functions to avoid loading large collections into PHP for charting.
• Date-range filters: if the card supports ranges, validate the input, cap the maximum range, and reuse the same query builder for each range.
• Zero-fill dates: charts often look broken when days with no records are missing. Generate the date spine in PHP or SQL and left-join aggregates onto it.
• Cache expensive cards: cache dashboard aggregates for short periods, keyed by tenant, user scope, date range, and filter state.
• Reusable base card: create an internal base chart card with shared options such as height, refresh behavior, colors, and empty-state handling, then subclass or configure it per chart.
• Permissions: chart endpoints are still application endpoints. Scope queries by tenant and apply the same authorization rules you would use for the underlying resource.
• Testing: unit-test the data provider output and feature-test that the card is registered and the endpoint returns the expected JSON shape.

A typical flow for a new chart:

1. Define the metric and date range.
2. Write a query/service that returns labels and series.
3. Create or configure the Nova chart card.
4. Register it on the dashboard or resource.
5. Verify with real and empty data.
6. Add caching and authorization scoping.

Gotchas and Tips

• Major-version upgrade risk: 4.0 is a Laravel 9 release, but the release notes do not include a detailed migration guide. Pin the version, upgrade in a branch, and smoke-test every dashboard card. If you cannot move to Laravel 9 yet, remain on 3.0.4.
• Nova compatibility: verify the required Nova version, not just Laravel. A Laravel 9 app can still have Nova version constraints that conflict with the package.
• Asset caching: after upgrading, run Nova’s asset publishing commands if applicable and clear caches. A stale compiled asset is a common reason a chart card loads but renders incorrectly.
• Config publishing: publish config only if you need to override defaults. Re-publishing after an upgrade can overwrite local customisations; diff before committing.
• Data shape mismatches: chart libraries are strict about labels, series names, and numeric values. Cast aggregates to integers/floats and keep the response shape stable.
• Empty datasets: decide explicitly whether to show an empty state, zeroes, or hide the card. Missing date buckets are usually a data-generation bug, not a frontend bug.
• Timezones: be consistent between database date truncation, PHP date handling, and Nova/user timezone settings. “Today” can span two buckets if this is ignored.
• Performance: dashboard cards are easy to add and easy to make slow. Index tenant/date columns, limit ranges, avoid N+1 queries, and cache expensive aggregates.
• Authorization: do not assume Nova’s dashboard authentication is enough. Scope chart data by tenant and policy-sensitive visibility.
• Debugging: inspect the browser network request for the chart endpoint, check storage/logs/laravel.log, confirm routes with php artisan route:list, and temporarily return a known static dataset to isolate frontend versus query issues.
• Extension points: custom chart card classes, package config defaults, publishable views/assets, and the Nova service provider are the main places to customise behaviour. Prefer extending a local card class over editing vendor files.