Filament Custom Tiptap Extensions Laravel Package

Technical Evaluation

Architecture fit. This is a narrow surface-area plugin: it registers additional Tiptap extensions into Filament's form-field layer via a service provider, and (almost certainly) ships published JS/CSS assets plus Blade views for custom node rendering. That makes it architecturally low-risk in the sense that it does not touch domain logic, persistence, queues, or auth — it is confined to the admin-panel presentation tier. The dependency chain is the real architecture question: filament/filament (v3 vs v4), awcodes/filament-tiptap-editor, the underlying Tiptap JS major, and Livewire/Alpine. Fit is good only if your Filament major and Tiptap editor version are explicitly in the package's supported matrix. If the extensions are things we would otherwise hand-roll (details/accordion blocks, anchors, alignment, color/highlight, custom attributes), the buy-vs-build math is favorable at first pass — but with 2 stars and 0 dependents we are effectively the first production consumer.

Integration feasibility. Straightforward mechanically: composer require, register the plugin on the panel, publish assets, add the extension classes to the Tiptap editor's ->extensions([...]) array, and configure the sanitizer profile so custom tags/attributes survive. The non-trivial work is downstream: every custom node needs a frontend renderer (Blade component or HTML parser), and content round-trip must be validated — Tiptap will silently drop unknown nodes/attributes when content is loaded and re-saved, which is a data-loss vector, not just a cosmetic one.

Technical risk. Ranked:

1. Bus factor / provenance. Single maintainer, 2 stars, 0 dependents, no downstream signal. No evidence of CI, test coverage, or a security disclosure path. Metadata anomaly worth clearing: the latest release is dated 2026-04-16, which is in the future relative to normal release cadence — verify the tag exists, is signed/attributable, and that the Packagist entry is not a mirror artifact.
2. Version coupling. Filament and Tiptap both move fast and both have made breaking asset/extension-API changes. The package's compatible constraint range is likely narrow and undocumented; a Filament minor bump could break the editor in production with no upstream fix.
3. XSS / sanitization. Custom nodes typically introduce new tags and attributes. If the extension definitions and HtmlSanitizer/purifier config drift, you get either stripped content (author frustration) or an injection path in an admin-authored field that renders on public pages.
4. Asset pipeline. Filament v3 Tailwind content scanning will purge classes used inside custom node views unless safelisted or the package ships prebuilt CSS. This surfaces as "works in local, looks broken in prod" — classic late-detection failure.
5. Editor ergonomics. Custom nodes with interactive UI (accordions, pickers) rely on Alpine lifetimes inside Livewire re-renders; state loss on wire:model dehydration is a known class of bug.

Key questions for the maintainer / spike.

• Exact supported matrix: Filament major(s), filament-tiptap-editor version, Tiptap major, PHP, Livewire.
• Full list of extensions and the exact HTML each emits — I want serialized fixtures, not screenshots.
• Are there automated tests? Any test fixtures for content round-trip?
• How are assets built and published (prebuilt dist vs build-on-install)? Is CSS safelisted for Filament v3?
• Storage format: HTML only, or JSON? Any content-versioning/migration story?
• Issue response expectation and a stated maintenance/support posture. If none, we plan to fork.

Recommendation. Conditional pilot, not a default dependency. Value is real if the extensions match a documented editorial requirement; risk is concentrated in unproven maintenance and version coupling, both of which are mitigable with pinning and a fork-in-waiting.

Integration Approach

Stack fit. Assumes Laravel 10/11+, PHP 8.2+, Filament v3 panel (v4 support unconfirmed — verify before committing), and awcodes/filament-tiptap-editor already in use or acceptable to adopt. If we are still on Filament's stock RichEditor (TinyMCE), this package is not a drop-in: adopting it forces an editor migration first. Treat the two as one decision, not two. If we have no editorial requirement for these specific node types, the correct answer is to decline and revisit when the package has dependents.

Migration path. Sequence it as a spike, not a rollout:

1. Spike branch (1–2 days). Install in an isolated panel, wire all extensions, and produce a fixture file per extension: author in the editor → capture stored HTML → render on a frontend page → re-open in the editor → diff. This test is the evaluation; publish the fixtures as the artifact.
2. Pin and vendor. Lock composer constraints ("wotz/filament-custom-tiptap-extensions": "x.y.*") and, if the spike passes, mirror the repo into our VCS as a read-only fork we can patch. Do not rely on upstream for a fix.
3. Sanitizer contract. Define the allowed tag/attribute set for each extension in our HTML sanitizer config before enabling authoring, and add a test asserting the sanitizer preserves the package's output. This is the gate.
4. Pilot on one low-traffic content type with a small author group; instrument editor JS errors and content-strip warnings.
5. Rollout to remaining rich-text fields only after a full release cycle with no round-trip diffs.

Compatibility and coexistence. Old TinyMCE-authored HTML will be re-parsed on first edit. Run a dry-run pass: load all existing records through Tiptap headlessly and diff before/after to enumerate what gets stripped (common casualties: inline styles, data-*, legacy classes). Decide per-casualty whether to add a permissive Tiptap extension, pre-normalize on save, or accept loss. Do not migrate fields where loss is unacceptable without a normalization script. Frontend rendering should be implemented as our own Blade components keyed to the emitted markup, so a future swap of the editor does not force a frontend rewrite.

Sequencing summary. Spike + fixtures → pin/fork → sanitizer contract → single-field pilot → normalization pass → broad rollout. Roughly 2–3 sprints of TPM-tracked work if the spike passes cleanly; abort at step 1 if the fixtures show silent data loss.

Operational Impact

Maintenance. We inherit the maintenance. With one maintainer and zero dependents, treat this as an internal fork with an occasional upstream sync rather than a supported dependency. Budget a standing ~0.1 FTE for the fork: dependency bumps on Filament/Tiptap releases, asset rebuilds, and fixture re-runs on each Filament minor. Add a calendar check tied to Filament release notes — that is the trigger event.

Support. No meaningful community support channel and no dependents to lean on for Stack Overflow answers. Escalation path is: read source, patch fork. That requires someone on the team comfortable with Tiptap's extension API and ProseMirror schema — a genuine and somewhat scarce skill. Confirm we have that person before adopting; if not, the risk profile changes materially.

Scaling. Editor-side cost is per-session, not per-request — negligible at our scale. The scaling concern is content volume on the read path if custom nodes require query-time parsing (e.g., accordion blocks that need server-side expansion). Prefer storing fully-rendered HTML or rendering via simple Blade partials so public page performance stays flat. No database or queue implications.

Failure modes to monitor.

• Silent content loss — highest severity; detection requires round-trip fixtures in CI. Without them you find out from an author.
• Asset/CSS breakage after deploy — Filament upgrade or Tailwind purge change; detect with a smoke test that renders one record per extension in staging.
• Sanitizer drift — content stripped on save after a security-config change; assert sanitizer output in tests.
• Editor JS errors on Livewire re-render — interactive nodes losing state; capture via client-side error reporting on the admin panel.
• Abandonment — upstream goes quiet; mitigated by the fork, so the risk becomes purely the cost of carrying patches.

Ramp-up. Low for developers wiring it up (half a day), moderate for the Tiptap/ProseMirror knowledge needed to safely patch or add an extension (days), low for authors (a short guide plus screenshots of each node). The scarce resource is the one engineer who understands the schema — document the extension list and the fixture suite so that knowledge is not single-threaded.