Nova Tiptap Laravel Package

Technical Evaluation

Architecture fit. A single-purpose Laravel Nova form field: a PHP field class (Manogi\Tiptap\Tiptap) that follows standard Nova conventions (component(), resolve, fill, field meta) paired with a Vue component that mounts the Tiptap headless editor inside Nova's form shell. It has no value outside Nova and no surface beyond "edit rich text on a resource form." For a TPM that is a favorable property — the blast radius is one field type on a bounded set of resources, not a platform dependency — but it also means the entire business case collapses if Nova is being replaced or admin tooling is being consolidated elsewhere. Confirm the Nova roadmap before sponsoring this work.

Integration feasibility. Straightforward for a team already competent in Laravel and Vue: register the field on a resource, configure a toolbar via ->buttons([...]), publish assets, done. The complications are not in wiring the field up but in everything downstream of it. The field persists a ProseMirror JSON document, not HTML, so the TPM's real scope is the rendering contract: how that JSON becomes HTML for the public front end, search index, API responses, email templates, and any mobile client. That renderer is ours to build and ours to keep in schema parity with the editor. Server-side sanitization (HTMLPurifier / mews/purifier) is likewise entirely our responsibility — the package provides none.

Technical risk. The dominant risk is ownership, not code quality. Archived repo, zero dependents, last release 2024-06-27, no upstream, no security response, no compatibility guarantee. Secondary risks are all classic Nova-field failure modes: Nova major / Laravel / PHP / Vue 2-vs-3 / bundled-Tiptap version mismatch; asset pipeline friction when compiling against the app's toolchain instead of Nova's; CSP headers blanking the editor with only console errors; the untouched-editor empty-doc case ({"type":"doc",...} instead of null) breaking nullable assumptions; and silent JSON→HTML→JSON round-trip loss of marks and nested lists. Custom nodes (callouts, embeds) are permanent forks of the Vue source, not configuration.

Key questions.

• Which Nova major are we on, and does the Composer constraint actually resolve against it? This is the go/no-go gate — verify before allocating sprint capacity.
• Do we need rich text at all, or does Markdown or a plain textarea satisfy the requirement? If Markdown works, this package is ownership overhead for a non-problem.
• Who is the named owner of the fork, and is that person/team staffed through the next Nova upgrade?
• What is the storage format empirically — confirmed in a spike, not inferred from the README — and what is the single shared JSON→HTML renderer?
• Is this editor surface internal/back-office (acceptable risk) or a regulated or high-traffic public front door (not acceptable without a maintained alternative)?
• Does a maintained Nova field alternative exist, and why are we not evaluating it first?

Integration Approach

Stack fit. Requires Laravel + Nova + Vue, with the field compiled against Nova's Vue and asset tooling rather than the host application's. Assume in-house Laravel/Vue capability and at least one engineer comfortable with ProseMirror concepts. Fit is excellent for teams already living in Nova; poor for anyone administering content through a separate CMS or headless stack.

Migration path. Fork first, install second. Point a Composer VCS path/vcs repository at the org fork of bastihilger/nova-tiptap, pin an exact tag, and treat the fork as source we own. Publishable assets via php artisan vendor:publish where applicable. Then a non-production spike on a single resource — a "Pages" or "Posts" form replacing the default text/Trix field — with explicit exit criteria: editor renders, saves, and reloads a real document, and we know exactly what hits the database column. If legacy CKEditor/TinyMCE exists elsewhere, this becomes the standardization candidate only after the storage-format and rendering story is settled, not before.

Compatibility. The full matrix must be proven, not assumed: Nova major, Laravel, PHP, Vue 2 vs 3, and the bundled Tiptap version must all line up simultaneously. The bundled Tiptap version is fixed — mixing extensions from a newer Tiptap major throws schema and command errors at runtime, so extension versions must match the bundled one or the whole editor must be upgraded deliberately. Pin Nova and PHP versions in CI and add a regression test that renders the field before any upgrade is considered complete.

Sequencing.

1. Compatibility gate — Composer constraint vs. Nova version. Fail here and the initiative stops.
2. Fork, pin the tag, write FORK.md (provenance, pinned versions, compatibility matrix, fallback path).
3. Non-production spike on one resource; empirically confirm stored format.
4. Build the shared JSON→HTML renderer and the server-side sanitization path; wire it into preview, index columns, API, and email templates. No raw JSON in Nova index columns or API responses — ever.
5. Add validation beyond json: a custom rule walking the doc for required node types, plus empty-doc normalization before persist.
6. Expand toolbar configuration per field (marketing Page gets headings/lists/links; a short bio gets bold/italic only) and add ->onlyOnForms() plus a read-only formatted detail view.
7. Seeders and factories use explicit ProseMirror docs, not plain strings, so fixtures match production shape.
8. Roll out resource by resource behind the sanitization and round-trip test suite.
9. Add the fork to the Nova upgrade checklist before the next major lands.

Decisions this forces. "Stay in Nova" vs. standing up a dedicated CMS is now an explicit roadmap call rather than a side effect of a field choice — for blog posts, help-center articles, landing copy, and email templates, a drop-in rich-text field often makes the cheaper answer defensible. Frame it as fork-and-own, not install-and-forget, and get that ownership model approved as a line item, not a footnote.

Operational Impact

Maintenance. Recurring and non-trivial relative to the package's size: patches at each Nova major, Tiptap extension alignment, CSP/asset-path adjustments, Vue toolchain drift. Budget roughly a day up front to fork, spike, and document, plus recurring upkeep around Nova upgrades and any custom-node work. Every custom Tiptap node added to the Vue source is a permanent fork with permanent cost — do it sparingly and only where the product genuinely demands it.

Support. There is no vendor path. Zero dependents means no community proxy for support either. Support is us: FORK.md documents provenance and pinned versions so the next maintainer isn't reverse-engineering choices, and a maintained fallback — a native Nova field plus a small custom Vue component — sits on the shelf before it's needed, not after. Do not put editor functionality on the critical path of a customer-facing launch without a named owner.

Scaling. Technically the field does not meaningfully scale-load anything — it's a form input, and the editor runs per-author in the admin panel, so concurrency is low. Scaling cost is organizational, not infrastructural: the number of resources using the field multiplies the renderer paths that must stay in schema parity, and each additional renderer (search index, email templates, mobile) is another place JSON→HTML drift can appear. Keep exactly one renderer shared between preview and production.

Failure modes. Blank editor (check in order: assets published and loading in the Network tab, component() name matches the compiled component, field meta serialized via withMeta/meta(), CSP); version-mismatch registration failure after a Nova or PHP bump; runtime schema/command errors from mixing Tiptap extension majors; empty-doc records that aren't null and break nullable validation; silent round-trip loss of marks and nested lists; and — the highest-severity one — XSS from stored HTML if sanitization is treated as a client-side concern. Mitigations: XSS regression tests, representative-document round-trip fixtures (not a single happy-path paragraph), and field-render regression tests in CI.

Ramp-up. Low for anyone who has built a Nova field before; moderate for the JSON→HTML rendering and sanitization work; high for anyone debugging a headless ProseMirror wrapper without Vue or ProseMirror experience — that is an expensive detour and a reasonable disqualifier if the team lacks it. Practical ramp: one engineer, one spike, one documented fork, then incremental resource-by-resource rollout. Accessibility conformance, RTL/i18n, and collaborative editing are not provided and would be built from scratch — treat any of those as a scope change, not a checkbox.