Filament Custom Tiptap Extensions Laravel Package

Getting Started

This release (v2.2.0) is a compatibility release, not a feature release: it adds PHP 8.5 / Laravel 13 support and bumps CI tooling (Composer install action, Dependabot metadata action). There are no new APIs, no deprecations, and no breaking changes called out. Treat it as a safe patch-level upgrade on your existing Filament panels — the only reason to prioritise it is if you're moving to Laravel 13 or PHP 8.5, in which case it is the first version that officially declares support.

Minimal steps:

1. composer require wotzebra/filament-custom-tiptap-extensions (or bump the constraint to ^2.2 if already installed).
2. Read the package README first — this package is a thin bridge between Filament's RichEditor field and TipTap's JS extension system, so the important documentation lives upstream in TipTap's extension reference, not in the PHP source.
3. Confirm your Filament version in composer.json — the package's 2.x line targets Filament v3/v4; mixing a v2 package with an older Filament major is the most common first failure.
4. First use case: register one of the bundled extensions (typography, text alignment, highlight, etc.) on a single RichEditor field, verify it loads in the browser, then generalise.

The fastest smoke test is a single RichEditor in one resource form, not a global registration. Get one extension rendering before you wire up panel-wide defaults.

Implementation Patterns

Per-field registration. Register extensions on the RichEditor instance itself where the field is declared. This keeps the blast radius small and makes it obvious in code review which forms use which extensions. Prefer this over panel-level registration until you have a stable set of extensions used everywhere.

Centralise the extension list. Once you have three or more forms using the same toolbar, extract the extension array into a config file or a small static registry class (e.g. app/Support/TiptapExtensions.php) that returns extension instances. Filament form classes then just spread that array. This makes it trivial to audit which extensions are live across the app and to add a new one in a single place.

Pair each extension with its toolbar button. A TipTap extension that adds a command (e.g. toggleHighlight) does nothing visible until you add the corresponding toolbar button to the RichEditor's toolbarButtons() array. Treat extension registration and toolbar configuration as one atomic change — commit them together, and add a note in the PR description. This is the number one source of "I installed it but nothing changed" bug reports.

Panel providers are the right place for global defaults. If you want every RichEditor in a panel to have the same extensions, do it in the PanelProvider::boot() or a dedicated service provider using the panel's richEditor() configuration hook rather than subclassing every form. Keep it declarative and avoid conditionals based on the current user inside the provider — push role-based differences into the form layer.

Use it for content-shape enforcement, not just cosmetics. The real day-to-day value is constraining what content editors can produce: alignment extensions plus a stripped toolbar give you a "headline block" editor; highlight and a limited heading scale give you a "callout" editor; a small extension set with a minimal toolbar makes stored HTML predictable and sanitisation easier.

Version the output. If extensions change the HTML they emit (new heading levels, new wrapper elements), that's a content migration, not just a code change. Note the HTML delta in the release/PR and check whether any front-end CSS or Blade rendering needs to know about new tags.

CI note for your own pipelines. The v2.2.0 Dependabot changes (ramsey/composer-install 3→4, dependabot/fetch-metadata 2.5.0→3.0.0) only affect the package's workflows. Nothing to mirror in your app unless you copied their .github/workflows as a template — in which case, update your composer-install action reference now rather than when it breaks.

Gotchas and Tips

The PHP side is not the feature surface. Almost all behaviour lives in bundled JS/asset files. If an extension "doesn't work", the PHP registration is rarely the culprit — check the browser console for a failed asset load, a TipTap version mismatch, or an extension name typo. php artisan filament:assets plus a hard refresh after upgrading the package is the standard first move.

Asset publishing is cached. Filament caches assets and, in production, caches components/icons. After upgrading to v2.2.0 run php artisan filament:assets and php artisan optimize:clear. A stale asset manifest will make it look like the upgrade broke something when it did not.

Laravel 13 support is declared, not proven in your app. "Add PHP 8.5 / Laravel 13 support" means the package's CI matrix likely includes it — but this package depends on Filament, which has its own Laravel 13 timeline. Before upgrading your app, confirm the Filament version you're pinned to also supports Laravel 13; otherwise you'll be upgrading into an unsupported combination and the failure will look like a TipTap bug.

PHP 8.5 is very new. If you're on 8.5 for other reasons, expect friction from other dependencies (Filament, Livewire, image/string extensions) long before this package is the problem. Keep a php: 8.4 CI job around until the whole dependency tree green-lights 8.5.

Pinning strategy. The 2.2.0 diff is CI-only plus a support-matrix widening, so ^2.2 is appropriate. Avoid pinning to an exact 2.1.x — you'd be forgoing a forward-compatibility release with zero behavioural risk.

Watch the Filament major boundary. The package's ^2.x line tracks a specific Filament major. A future Filament major will require a new package major, and because the coupling is asset-level (not just PHP), an accidental "works on my machine" upgrade will fail at runtime in the browser, not in Composer. Read the package's composer.json require block after any Filament upgrade.

Extension points to lean on. Prefer the package's registration API over monkey-patching Filament's RichEditor or editing published views. If you hit a missing capability, the maintainable move is a small custom TipTap extension of your own registered alongside the bundled ones — that survives package upgrades, whereas patched vendor views do not.

Debugging checklist, in order: (1) asset rebuild + hard refresh, (2) browser console for JS errors, (3) confirm the extension name matches TipTap's canonical name, (4) confirm the toolbar button for the command exists, (5) confirm the Filament major matches what the package expects. Only after all five should you go reading the package source.

Low-maintenance signal worth noting. This release is mostly bot-authored (Dependabot plus a Copilot PR). That's normal and healthy for a glue package, but it does mean the code surface is small and the real upstream risk is TipTap/Filament breaking changes rather than bugs in this repo. Budget review time for Filament upgrades accordingly, and keep an eye on the package's issue tracker when a new Filament minor lands.