Nova Version Card Laravel Package

Getting Started

kussie/nova-version-card is a small Laravel Nova card that surfaces the deployed application version in the Nova UI — useful for support workflows where you need to confirm which build a user is on before reproducing an issue.

1. Install into an app that already has Nova set up:

   composer require kussie/nova-version-card
   

2. Register the card in app/Nova/NovaServiceProvider.php inside cards():

   public function cards()
   {
       return [
           new \Kussie\NovaVersionCard\VersionCard(),
       ];
   }
   

3. Load the dashboard. If nothing renders, the version source isn't configured — see Gotchas.

Where to look first (in this order):

• src/VersionCard.php — the $component, component() and any withMeta() payload. This tells you what the Vue component expects.
• src/VersionController.php — the file touched in v0.1.2. This is where the version string is resolved (config key, composer.json, git tag, or an env var).
• routes/ (or the boot() method in the service provider) — cards usually expose a /nova-vendor/... endpoint the component calls on mount.

First use case: drop the card on the main dashboard next to your other metrics so on-call engineers can read the live version at a glance instead of shelling into the server.

Implementation Patterns

Pin the version source explicitly. Rather than relying on defaults, set a single canonical value in config/app.php (or a dedicated config/nova-version-card.php if the package publishes one) and have every environment populate it the same way:

// config/app.php
'version' => env('APP_VERSION', 'dev'),

Inject the version at build/deploy time. This is the pattern that actually holds up: have CI write the git tag into the environment or .env during deploy. Reading composer.json at runtime works but drifts the moment someone forgets to bump it, and it breaks on read-only filesystems or when composer install --no-dev runs from a different working directory.

Placement matters more than the card. Common integrations:

• Dashboard card for a global view.
• NovaServiceProvider::cards() scoped per-environment via a Gate::define or a simple if (app()->environment('production')) guard, so staging/dev cards don't clutter prod.
• A custom Main dashboard or a Resource detail page where support staff already are.

Pair it with a "latest release" source. If the controller returns only the deployed version, consider a small custom card or an override that also fetches the latest tag from your git host — then the card communicates drift, not just a static string. Don't fork the vendor file to do this; extend the card class or swap the controller binding instead.

Multiple apps / multi-tenant. Because the card is registered globally in NovaServiceProvider, multi-tenant setups will show the same version everywhere. If tenants deploy independently, wrap card registration in a request-aware resolver or register cards per-tenant in a custom dashboard.

Gotchas and Tips

The version source is the whole ballgame — verify it before debugging anything else. Open VersionController.php and read exactly what it returns. If it reads a config value, php artisan config:cache will freeze it until you re-cache; a deploy that writes .env after config:cache runs will show a stale version forever. Order your deploy steps accordingly.

Check the route middleware. Nova cards call routes registered by the package, typically under a nova middleware group. If the card renders but the version shows blank or you get a 401/403, hit the network tab, find the failing /nova-vendor/... request, and confirm the route exists with php artisan route:list | grep -i version. If the package registered the route outside Nova's auth stack, that's a security smell worth reporting upstream.

Nova version compatibility. Verify the composer.json constraint on laravel/nova matches your installed major (Nova 4 vs 5 differ in card asset handling and Vite vs Laravel Mix). This is a 0.x package; don't assume forward compatibility.

Assets not showing after install/update. Run php artisan nova:publish (and vendor:publish if the package ships tagged assets). A card that renders as an empty box is almost always an unpublished/missing compiled JS asset, not a logic bug.

Treat 0.x releases as untrusted until diffed. v0.1.2 is a single-file change to VersionController.php from a first-time contributor. Before bumping, run composer diff kussie/nova-version-card or read the PR — for a package that runs inside your admin panel, a controller change is exactly the kind of surface you want to eyeball. Pin with a ~0.1.2 constraint rather than ^0.1 style wide ranges if you want tighter control.

Debugging checklist, in order: card visible? → JS asset published? → network request firing? → route registered + middleware correct? → controller returning the expected string? → config cached?

Extension points. Prefer overriding the Vue component via VersionCard::component() or withMeta() over editing vendor files, so composer update stays clean. If you need a different data source, subclass the card and override the controller resolution rather than patching the package.