Richie Laravel Package

Technical Evaluation

Architecture fit. Richie is not a platform component — it is a form field that mounts a Tiptap/ProseMirror editor inside a Filament v3 panel, plus a Blade render path from stored JSON to HTML. That constrains the decision sharply: the package only has a surface to attach to if you are already on Filament v3 (Laravel 10/11). If Filament adoption is a live roadmap question, evaluate it separately and first. An editor requirement must not be the camel's nose that drags a whole admin-UI framework into the architecture, because the editor is a small problem and the panel migration is a large one. Where Filament is already the standard, the fit is good: the field composes into resource forms with no bespoke JS, and the composition model (toolbar actions configured per field or via named profiles) matches how content teams actually want editors to differ between a "short bio" and a "long-form article."

Integration feasibility. Low-to-moderate effort — realistically a few days for a first field end to end, not a sprint. The blockers are not conceptual, they are unknowns: whether the JSON→HTML renderer described in the README actually ships at 0.1.3 or is roadmap; the real namespace and make() signature; whether assets are precompiled or require your app's Vite pipeline; and where image uploads land. Each is a question the source answers in an hour and the README does not answer at all. Treat the src/ directory as the documentation during the spike. The v0.1.3 changelog is a single line — actions now register on the editor instance rather than globally — which is simultaneously a correctness fix and evidence that the action/toolbar API is still settling.

Technical risk. Two risks matter at the product level, and only one is about the code.

The first is content durability. The realistic production incident is not an outage, it is silent content loss: an asset-pipeline or Filament bump breaks editor hydration, the field renders blank, the form saves blank content over a good document, and nobody notices until an author complains. A save-time guard that rejects empty-over-nonempty is cheap insurance and should be treated as a launch requirement, not a nicety.

The second is sanitization posture, which is unverified anywhere in this repository. Editing is admin-side and semi-trusted; rendering may not be. Any surface where the output reaches a browser without a sanitizer you own — public UGC, syndicated content, email export, anything compliance-sensitive — is out of scope until that gap is closed. That is a product call with a safety dimension, not a technical preference.

Third-order but real: stability. Three patches into a 0.1 line, one maintainer, seven stars, zero dependents. Zero dependents is the number to sit with — it means no one has hardened this against your use case, and you will be first through most edge cases.

Key questions to close before committing.

• Is the render path shipped at 0.1.3, or is this an authoring tool only?
• Are assets precompiled, or does an admin form control now sit downstream of our front-end build?
• Where do uploads go, and does it delegate to Filament's uploader or medialibrary?
• Is the source small enough that one of our engineers can read and patch it during an incident?
• Who is the named internal owner, and what is the fork-and-vendor trigger?

Integration Approach

Stack fit. Adopt only where Filament v3 is already the admin standard. Pin awcodes/richie:0.1.3 exactly — never a caret range on a 0.1 line with a single maintainer. Publish the config and assets, review what the config exposes before accepting defaults, and confirm the asset story on a clean checkout rather than a warm local environment.

The decision that outlives the package. Persist Tiptap JSON as the source of truth and derive HTML at render time; optionally store rendered HTML alongside for search and indexing. This is the one choice the PM should insist on owning in design review, because it determines schema, search strategy, API serialization, and — most importantly — how cheaply you can swap editors in eighteen months. Raw HTML blobs forfeit all of that. The front end and any API must consume sanitized derived HTML, never the raw document; returning ProseMirror JSON to a public API is worse than useless and leaks node structure into your contract.

Compatibility and coupling. The dependency is not really on Richie — it is on Filament's asset and form internals, which move independently of Richie's release cadence. Gate every bump, Richie's and Filament's, on the editor regression suite passing. The specific regression worth writing permanently is multi-instance isolation: two editors on one form must keep distinct toolbars and distinct documents. That is precisely what 0.1.3 fixed, so it is where the next break will land.

Sequencing.

1. Spike — read src/, resources/js/, config/richie.php; resolve the field-versus-renderer ambiguity; verify assets.
2. Wrap it — one internal RichText class extending the package field, so call sites never reference Awcodes\Richie\Richie directly. Cheap now, expensive after fifty resources.
3. First field on one internal content type — one editor, one resource, save → reload → render round trip verified end to end. Not the model with three rich-text fields.
4. Launch behind a config flag with a plain Textarea fallback wired and tested.
5. Widen after one clean patch upgrade with the regression suite green.
6. Defer custom tools, per-field toolbar profiles as a committed roadmap item, and any multi-editor layout until the shape of step 3 has held for a release.

Operational Impact

Maintenance. This is the dominant cost and it should be budgeted explicitly. Single maintainer, GitHub issues only, no SLA, no deprecation policy. Name an internal owner and a quarterly review slot before the second content type depends on it, not after the fifth. Decide the fork-and-vendor trigger in advance — if the project stalls past one release cycle or the action API churns again, the plan is to vendor the source, not to scramble. Verify the codebase is small enough to read and patch during the spike, while the pressure is low, rather than during an outage.

Support. There is none in the contractual sense. Internal ramp-up is realistic: an engineer familiar with Filament and Tiptap can be productive in a day, and the integration surface is small enough that the "support burden" is really one person's attention plus a regression suite. That is acceptable for an internal authoring tool and unacceptable for anything on the primary customer-facing authoring path.

Scaling. Server-side scaling is a non-issue — this is a form control. The scaling problem is storage and retrieval: rich-text JSON is verbose, a few KB per record compounds into database size, full-text index bloat, and payload weight on any endpoint that returns it verbatim. Index the rendered-and-sanitized HTML, never the JSON; matches on ProseMirror node types and attribute names are noise. Client-side, the number of editors per page is the practical limit, and that is exactly the untested path.

Failure modes to plan for.

• Hydration failure after an upgrade → blank field saves over good content. Mitigation: save-time guard throwing a validation error on empty-over-nonempty, plus the Textarea fallback behind the flag.
• Cross-instance action leakage → wrong toolbar in the wrong field, or an action operating on the wrong document. Mitigation: the permanent multi-editor regression test.
• Upstream stall → no fixes for Filament compatibility breaks. Mitigation: named owner, fork trigger, and a source small enough to vendor.
• Unsanitized render → stored XSS on any user-visible surface. Mitigation: a sanitizer in a single renderer concern that you own, with a fixed allowlist, at every boundary that reaches a browser.

Ramp-up. Low, and the cost profile is front-loaded: an hour reading the source answers more than the README does, and the wrapper class plus the two safety tests are perhaps a day of work that pays for itself on the first package bump. The honest framing for the roadmap is that Richie buys a head start of a few days of integration work — not a support relationship — and it is worth taking only where the authoring surface is internal, the version is pinned, and someone owns the exit.