Rich Text Editors skill for Claude Code

A production editor has a schema that only allows what the product supports, stores a structured document (JSON) as the source of truth, renders and sanitizes HTML on the server, cleans pasted content through the schema, and treats every byte from the client as untrusted.

Step 0 — inspect

npm ls @tiptap/react @tiptap/core @tiptap/starter-kit lexical @lexical/react prosemirror-model yjs @hocuspocus/provider
grep -rn "dangerouslySetInnerHTML\|v-html\|innerHTML" src app | head        # where editor output is rendered
grep -rn "getHTML()\|getJSON()\|editorState.toJSON" src app | head          # what gets stored

Find out what the product needs: formatting set, embeds (images, mentions, links, tables, code), comments, collaboration, markdown import/export, mobile support, and where content is displayed (web, email, native app).

Library choice

Need	Pick
React/Vue/Svelte app, standard formatting plus custom nodes, fastest to ship	Tiptap 3 (ProseMirror underneath, MIT core)
Meta-style plugin model, React-first, fine-grained node classes, large docs	Lexical
Unusual document model, maximum control, you own the toolbar and plugins	ProseMirror directly
Plain comments with bold/italic/links only	A textarea with markdown + server render, or Tiptap with a tiny schema
Block-based Notion-like UX out of the box	BlockNote (built on Tiptap)

Do not hand-roll contenteditable with document.execCommand — it is deprecated, inconsistent across browsers, and produces unsanitizable markup.

Storage contract

Store	Why
JSON document (Tiptap editor.getJSON(), Lexical editorState.toJSON())	Source of truth; validates against schema; migratable
Rendered, sanitized HTML (optional cache column)	Fast display, email, search snippets — regenerated from JSON
Plain text (optional)	Search indexing, notifications, previews

• Validate JSON on the server against the same schema before saving (Tiptap: getSchema(extensions) + Node.fromJSON(schema, json) throws on invalid content).
• Version the document format ({ schemaVersion: 3, doc }) so you can migrate stored content when nodes change.
• Never store client-produced HTML as trusted. If you must accept HTML (imports, legacy), sanitize on the server with an allowlist.

Tiptap 3 setup (React)

import { useEditor, EditorContent } from "@tiptap/react";
import { BubbleMenu } from "@tiptap/react/menus";
import StarterKit from "@tiptap/starter-kit";
import Placeholder from "@tiptap/extension-placeholder";
import Image from "@tiptap/extension-image";

export function PostEditor({ initial, onChange }: Props) {
  const editor = useEditor({
    extensions: [
      StarterKit.configure({
        heading: { levels: [2, 3] },                    // only what the design supports
        link: { openOnClick: false, autolink: true, protocols: ["http", "https", "mailto"] },
      }),
      Placeholder.configure({ placeholder: "Write something…" }),
      Image.configure({ allowBase64: false }),        // force uploads, no data: URIs in docs
    ],
    content: initial,                                 // JSON, not HTML
    immediatelyRender: false,                         // required with SSR (Next.js, Remix) to avoid hydration mismatch
    shouldRerenderOnTransaction: false,               // v3 default; read state with useEditorState for toolbars
    onUpdate: ({ editor }) => onChange(editor.getJSON()),
  });
  return (
    <>
      {editor && <BubbleMenu editor={editor}><Toolbar editor={editor} /></BubbleMenu>}
      <EditorContent editor={editor} className="prose" />
    </>
  );
}

Tiptap 2 → 3 changes that break code:

• StarterKit now includes Link and Underline — remove separate registrations or disable the bundled ones (StarterKit.configure({ link: false })) to avoid duplicate extension warnings.
• BubbleMenu/FloatingMenu import from @tiptap/react/menus (or @tiptap/vue-3/menus); Tippy.js replaced by Floating UI (tippyOptions → options; add @floating-ui/dom).
• CollaborationCursor became CollaborationCaret; history is UndoRedo in StarterKit (disable it with collaboration: StarterKit.configure({ undoRedo: false })).
• Toolbars that show active marks: use useEditorState({ editor, selector }) rather than re-rendering on every transaction.

Read the official v2 → v3 upgrade guide for the full list before migrating.

Lexical essentials

• LexicalComposer with initialConfig: { namespace, nodes: [HeadingNode, ListNode, ListItemNode, LinkNode], onError, theme }.
• Register only the nodes you need; unknown nodes in stored JSON throw on parse.
• RichTextPlugin, HistoryPlugin, ListPlugin, LinkPlugin, OnChangePlugin (serialize with editorState.toJSON(); debounce saves).
• Mutate only inside editor.update(() => ...); read inside editorState.read(...).
• Server HTML: @lexical/headless + $generateHtmlFromNodes (needs a DOM shim such as jsdom/happy-dom on Node), then sanitize.

Rendering output safely

// server: JSON → HTML → sanitize → cache
import { generateHTML } from "@tiptap/html";          // works on the server in v3
import sanitizeHtml from "sanitize-html";

const html = generateHTML(doc, extensions);           // same extension list as the editor
const safe = sanitizeHtml(html, {
  allowedTags: ["p", "h2", "h3", "strong", "em", "u", "s", "a", "ul", "ol", "li", "blockquote", "code", "pre", "img", "br", "hr"],
  allowedAttributes: { a: ["href", "rel", "target"], img: ["src", "alt", "width", "height"] },
  allowedSchemes: ["http", "https", "mailto"],
  transformTags: { a: sanitizeHtml.simpleTransform("a", { rel: "noopener noreferrer nofollow" }) },
});

• In the browser, DOMPurify (DOMPurify.sanitize(html, { USE_PROFILES: { html: true } })) before any innerHTML/dangerouslySetInnerHTML/v-html.
• Block javascript: and data: URLs on links and images even if the editor’s link extension validates them — the API can be called without the editor.
• Images: only from your upload domain/CDN; strip on* attributes, style, class unless allowlisted.
• Add a Content-Security-Policy to pages that display user content (see security-headers).

Paste and input handling

• Pasted HTML is parsed through the schema: unsupported tags are dropped, which is the main defense against Word/Google Docs junk. Keep the schema tight.
• Strip inline styles and classes on paste (transformPastedHTML in ProseMirror/Tiptap editorProps) if marks with attributes (color, font) are not product features.
• Pasted images arrive as files: intercept (handlePaste/handleDrop), upload, then insert the node with the returned URL; show a placeholder node while uploading and remove it on failure.
• Markdown shortcuts (## , - , > , ```) come from input rules in StarterKit and Lexical’s MarkdownShortcutPlugin; keep them, users expect them.

Custom nodes

• Prefer a node with plain renderHTML/parseHTML first; reach for a React/Vue node view only for interactive content (embeds, mention chips with popovers, callouts with pickers). Node views are costly in long documents.
• Define parseHTML rules for every node so copy/paste between documents round-trips.
• Atom nodes (atom: true) for embeds that should be selected and deleted as one unit.
• Mentions: suggestion utility → popup list → insert node with { id, label }; resolve the user server-side when rendering, never trust the label for permissions.

Collaboration

Yjs is the default CRDT for both Tiptap (@tiptap/extension-collaboration + @tiptap/extension-collaboration-caret) and Lexical (@lexical/yjs + CollaborationPlugin). Server options: Hocuspocus (Tiptap’s open-source Yjs server), y-websocket, Liveblocks, or Tiptap Cloud. For the setup, persistence, auth and snapshot details read references/collaboration-yjs.md when adding multiplayer.

Gotchas

• immediatelyRender: false missing in SSR apps → hydration error on load.
• Setting content on every React render resets the cursor; pass initial content once and use editor.commands.setContent only when switching documents.
• Saving on every keystroke: debounce (500–1000 ms) and also save on blur and beforeunload/visibilitychange.
• Empty editor returns <p></p>, not an empty string; use editor.isEmpty for validation.
• Character limits: CharacterCount extension with limit enforces in the editor; the server must enforce too.
• Mobile Safari/Android IME: test composition (Japanese, Chinese, Android Gboard autocorrect); avoid key handlers that intercept during composition.
• Large documents (>50 pages) need care: avoid node views in repeated nodes, and do not getJSON() on every transaction.

Verification

1. Paste from Google Docs, Word, and a web page: output contains only schema nodes, no inline styles or spans with classes.
2. XSS test: submit JSON with a link javascript:alert(1), an image with onerror, and raw <script> in a text node via the API (bypassing the editor); rendered page executes nothing and the server rejects or strips them.
3. Round-trip: load stored JSON → edit → save → reload; no content loss, cursor stable.
4. SSR page loads without hydration warnings; keyboard shortcuts and undo work.
5. Collaboration (if any): two browsers edit the same paragraph simultaneously; both converge, and reconnecting after offline edits merges without loss.

Report format

**Editor:** Tiptap 3.x (StarterKit headings 2–3, link, image upload, mentions)
**Storage:** JSON (schemaVersion 2) + sanitized HTML cache via sanitize-html allowlist
**Paste:** styles stripped, images uploaded to /uploads with placeholder node
**Security:** server schema validation, link schemes http/https/mailto, CSP on /posts
**Verified:** paste matrix, XSS payloads via API, round-trip, no hydration warnings