Nova Tiptap Laravel Package

Product Decisions This Supports

• Build vs. buy for admin authoring. MIT license, small code surface: the buy case is cheap in both money and lines of code. Reframe the decision honestly — it is wrap an existing field versus build and own an editor integration outright, not free versus expensive. The real cost shifts from "write an editor" to "evaluate, pin, wrap, and steward a single-maintainer dependency."

• Capability-gap triage against Nova's own field. Nova 4+ already ships a first-party Tiptap field. That converts the roadmap question from "do we want rich text?" into "which named capabilities are missing?" — custom toolbar layouts, mention nodes, tables, media/video nodes, markdown input rules, or parity with a Tiptap editor already running in the front end. If the answer is "plain formatted text," the correct product call is to use what Nova provides and spend attention elsewhere. This package only earns a slot when a specific gap can be written down in one sentence.

• Feature scoping and sequencing. Informs whether rich-text authoring belongs in the near-term admin roadmap at all — blog drafts, product descriptions, help-center articles, email snippets, internal docs. When the need is real and internal, it compresses time-to-pilot to roughly a sprint. When the need is speculative, it adds an editor stack the team must support for no near-term payoff.

• Editor standardization as a strategic argument. The strongest adoption case is consistency. If the product already runs Tiptap on the front end, using it in Nova means one mental model, one extension ecosystem, one set of rendering concerns. If the product uses something else, this introduces a second editor stack — a modest but real long-term tax that belongs in the decision, not the footnotes.

• The content contract — a product call, not an implementation detail. Whether the field persists HTML or ProseMirror JSON determines what search, feeds, exports, mobile, and localization can do later. HTML is universally consumable but lossy; JSON preserves the document model but forces every downstream consumer to carry a renderer. Product should own this explicitly, because it decides which future features are cheap and which become a conversion project.

• Risk-tiered rollout planning. Twenty stars and zero dependents is a planning input, not a veto. It supports piloting on internal, low-blast-radius surfaces — where a broken editor costs an afternoon, not a customer — and deferring any customer-facing publishing surface until the dependency has survived a release cycle or two.

• Make-vs-extend on CMS strategy. Clarifies whether the roadmap needs a governed content platform (workflows, approvals, versioning, audit, localization) or just a better text box in the back office. This package is firmly the latter. Choosing it signals light-touch content operations; choosing otherwise signals that content is becoming a product surface in its own right.

• Reversibility as a design constraint. Exit cost is genuinely days, not months — but only if engineering wraps the field in a single internal class rather than referencing the package across dozens of Resources. That wrapper is a product-level safeguard: it keeps the bet small and the rollback cheap.

When to Consider This Package

Consider it when most of the following hold:

• You are already committed to Laravel Nova. This is an admin-plane dependency with no value outside Nova. It is not a general Laravel editor package, and it does nothing for public-facing or API-side authoring.

• A concrete, nameable capability gap exists versus Nova's built-in Tiptap field. Name the gap before evaluating — specific extensions, toolbar behavior, mention or media nodes, markdown input rules. "We want rich text" is not a gap.

• The authoring surface is internal and low-risk. Drafts, internal docs, product copy staging — not regulated content, not a customer-facing publishing surface on day one. Prove the dependency on a surface where a blank editor costs an afternoon.

• Tiptap is already the house editor. If the front end runs Tiptap, this is consolidation rather than a new stack, and the extension/rendering knowledge is already paid for.

• Someone on the team has, or will acquire, Tiptap/ProseMirror literacy. Anything beyond a default toolbar requires schema, node, mark, and extension fluency. That learning curve — not the package — is the hidden cost.

• You have an explicit, written storage decision (HTML vs. ProseMirror JSON) and a server-side sanitization boundary at the write path. Without both, you are shipping an XSS surface and a future conversion project.

• You can pin the version hard. Commit the exact version and record the tested matrix (Nova major × Tiptap major × PHP version). No floating ^ on a single-maintainer package with zero dependents.

Look elsewhere — or use Nova's native field — when:

• The requirement is plain formatted text. Nova 4+ already solves this. Paying a dependency-stewardship tax for parity is a bad trade.

• The roadmap includes editorial workflow. Approvals, scheduling, versioning, localization, audit trails — none of that is here, and bolting it onto a field is the wrong shape of investment. That is a content-platform decision.

• Nobody can name the gap, or nobody owns the Tiptap learning curve. Scope the first ticket as a time-boxed spike with "we learned the schema" as a valid deliverable — or defer.

• The surface is customer-facing on day one. With ~20 stars, zero dependents, and an unverified Nova × Tiptap × build-toolchain compatibility triangle, the first production exposure should not be a revenue-adjacent publishing surface.

• Inline media is required and the package ships no upload path. Wiring a media node to your own upload endpoint — endpoint, authorization, node view, delete cleanup — is real scoped work. Budget it, don't assume it.

How to Pitch It (Stakeholders)

For executives (one paragraph): We need a better authoring experience in the Nova admin. Nova already includes a basic rich-text field, so the honest question is not "buy an editor" — it is "does a specific, nameable capability justify a small third-party dependency?" This package is MIT-licensed, roughly a sprint to pilot, and reverses in days rather than months provided we wrap it in a single internal class. It carries real but bounded risk: one maintainer, twenty stars, no dependents, and an unverified compatibility matrix. The recommended path is a low-blast-radius pilot on an internal surface — drafts or internal docs — with a go/no-go after one release cycle, before it touches anything customer-facing. What it does not buy us is a content platform: no approvals, scheduling, versioning, localization, or audit trail. If those appear on the roadmap, that is a separate and larger decision.

For engineering (the asks):

• Wrapper first, always. Every Resource references our own App\Nova\Fields\RichText, never the package class directly. That one file is our entire exit cost — and our swap, fork, or abandonment plan.
• Prove the compatibility triangle in a throwaway branch before committing: Nova major × Tiptap major × build toolchain (Mix vs. Vite). The failure mode is a silent blank editor, not a composer conflict.
• Decide the storage format once and encode it in the wrapper. HTML or ProseMirror JSON, written down, applied via accessor/mutator or cast so it cannot drift per-Resource. Product owns this call; engineering owns preventing drift.
• Enforce sanitization server-side at the write boundary (model observer or equivalent), with an allowlist equal to or stricter than the toolbar. Client-side schema constraints reduce malformed markup but do not stop paste.
• Pin the exact version. Record the tested matrix in the repo README. An unpinned composer update is how we discover a breaking change as a blank editor rather than a changelog.
• Add CI that runs the Nova asset build, plus one browser smoke test asserting the editor mounts and accepts input on one Resource. That single test catches the failure mode that actually hurts.
• Roll out one Resource per PR. Never bulk-swap every editor field in a release. If the component breaks on mount, blast radius should be one admin screen.
• Test the contract, not the editor. Sanitization assertions on save, plus the mount smoke test. ProseMirror internals are not unit-testable and chasing that is wasted effort.
• Before rollout, exercise paste from Word, Google Docs, and a page with a table and code block, and confirm the editor repopulates correctly after a Nova validation-failure redirect. Those two paths are where users report "it lost my content."
• Decide the index view up front — plain-text excerpt via displayUsing(), or exclude the field and surface a derived excerpt attribute. Raw HTML in a Nova index column renders as a wall of markup.
• Keep the surface thin so the fork stays cheap. No package API calls scattered through Resources, and reach for extension points before editing vendor code. If the toolbar is fixed and no extension registration is exposed, treat that as a hard ceiling — verify it before building a feature on top.