Nova Grapesjs Page Builder Laravel Package

Getting Started

This package is a Laravel Nova extension; the v0.2.1 release is a compatibility bump to Nova 5. Treat Nova 5 as the supported baseline going forward.

1. Confirm the Nova constraint. Nova is distributed via a private Composer repository, so the package cannot install without Nova already resolvable. Check composer.json for laravel/nova: ^5.0 and ensure your auth.json / COMPOSER_AUTH contains your Nova credentials before running anything.
2. Install pinned. Because the package is pre-1.0, install with an explicit constraint (composer require vendor/package:^0.2.1) rather than a floating *. Minor releases in 0.x are allowed to break.
3. Publish and register. Run the package's vendor:publish tag(s) for config and any compiled assets, then register the tool/card/field in app/Nova/NovaServiceProvider.php — tools() for a full-page tool, cards() for a dashboard card, or via Nova::resources()/field resolution for resource-level pieces. Consult the package README for the exact class name; it is the authoritative source here.
4. First use case. Load the Nova dashboard and confirm the tool renders before wiring real data. This isolates Nova 5 asset/registration problems from your application logic.

If you are upgrading from an earlier 0.x, the practical first step is a throwaway branch: bump the package and Nova together, run php artisan nova:publish, rebuild frontend assets, then load the dashboard. Doing both upgrades in one commit is fine; doing them across two makes the failure ambiguous.

Implementation Patterns

Keep Nova coupling at the edges. Nova tools tend to leak into controllers and models. Wrap package interactions in a small service or action class so your domain code stays testable without booting Nova's HTTP stack.

Authorization belongs in Nova, not the tool. Use Nova's canSee / authorizedToView hooks and Nova gates rather than conditional rendering inside the tool component. This keeps visibility rules consistent with the rest of your Nova resources and survives package upgrades.

Configuration over forking. Most Nova packages expose behaviour through a published config file. Prefer config and per-instance constructor options (labels, filters, default sort) over editing the package's Vue components — forked components are the single most common source of "works locally, blank panel in production."

Multi-panel and menu placement. If you run more than one Nova panel, register the tool in each panel's provider (or a shared base provider) and set $menu/$menuIcon deliberately. Duplicate registrations across providers produce the tool appearing twice, which is easy to miss because both entries work.

Test with Nova's helpers where available. Nova ships testing utilities for resource and action flows. For a tool, a simple feature test asserting the route returns 200 for an authorized user and 403 for an unauthorized one catches the majority of registration regressions cheaply, and runs fast enough for CI.

Version your CI matrix deliberately. If you still support Nova 4 consumers, test both; if not, drop Nova 4 from the matrix in the same release that declares Nova 5 support, so the claim in the README matches what CI actually proves.

Gotchas and Tips

• Nova credentials are the #1 CI failure. Missing COMPOSER_AUTH in CI surfaces as "package not found" rather than an auth error, which sends people hunting for tag typos. Set the secret first.
• 0.x semver is not a stability promise. ^0.2.1 permits 0.3.0, which may break you. Pin exact versions in production and upgrade intentionally.
• Version numbers don't guarantee coexistence. A package release claiming "Nova 5 compatibility" does not verify it against your Nova minor. Read the package's composer.json require block for the actual Nova constraint — that is the contract, not the release note.
• Stale compiled assets are the most common "it broke after upgrade." Nova 5 uses a Vite-based asset pipeline; after upgrading, run php artisan nova:publish, clear view:clear and config:clear, and delete any orphaned public/vendor/nova artifacts. A 404 on a hashed JS chunk in the browser console is the tell.
• Blank panel, no error? Check the browser console before the Laravel log. Nova tool failures are usually client-side: a missing manifest entry, a component name mismatch, or a Vue version conflict.
• Cache-busting across deploys. If the package ships assets, ensure your deploy pipeline rebuilds them rather than relying on the committed build output, otherwise a release that only bumps compatibility can silently serve old JS.
• Debugging registration. php artisan route:list --path=nova confirms whether the tool's routes exist; if they don't, the problem is NovaServiceProvider, not the component.
• Extension points to prefer: config file, published migrations, per-instance options, and Nova's Nova::script() / Nova::style() hooks. Avoid subclassing package internals or patching vendor files — both are invisible to code review and vanish on the next composer update.
• Watch the release cadence. A lone compatibility bump with no changelog detail is a signal to read the diff, not the note. Check whether the Nova 5 change touched composer.json only or also shipped functional changes; if the latter, re-verify the tool renders before trusting the upgrade in production.