tiptap — Claude Code skill: editor setup and install
This skill guides React editor setup with Tiptap, including extensions, SSR, image uploads, and Y.js collaboration. Use it when adding rich-text editing to an app.
MIT 117 installs ★ 29 updated 2026-08-17
npx skills add oakoss/agent-skills --skill tiptap -a claude-codeWhat tiptap does
The skill walks through building a Tiptap editor in React: creating it with useEditor(), rendering it with EditorContent, and adding extensions for tables, images, Markdown, and code highlighting. It also covers text styling and collaborative editing with Y.js.
For SSR, including Next.js, set immediatelyRender: false in the useEditor() options. The hook can return null, so check the editor before calling its methods. With Y.js collaboration, turn off undo and redo using undoRedo: false. Create React App does not work with Tiptap v3's ESM module layout; the skill points to Vite instead.
For image handling, the guidance replaces base64 storage with an upload flow that updates the image URL. React integration uses @tiptap/react, while @tiptap/pm is listed as a required peer dependency. Account for that dependency when setting up the project.
What it helps with
- configure a Tiptap editor for SSR in a React app
- set up StarterKit extensions and heading levels
- upload images and replace them with URLs
- add Markdown or tables to an editor
- configure Y.js collaborative editing
Example prompts for the agent
- Set up a Tiptap editor in my Next.js app and configure
useEditor()for SSR. - Change image handling so uploads use URLs instead of base64 data.
- Add Y.js collaboration and turn off undo/redo in
StarterKit.
How to install tiptap
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tiptap -a claude-code2Manually: put the files in place
~/.claude/skills/tiptap/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/tiptap/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tiptap -a codex2Manually: put the files in place
.agents/skills/tiptap/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tiptap -a cursor2Manually: put the files in place
.cursor/skills/tiptap/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/tiptap2Manually: put the files in place
.github/skills/tiptap/SKILL.md1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tiptap -a gemini-cli2Platform CLI
gemini skills install https://github.com/oakoss/agent-skills --path skills/tiptapManually: put the files in place
.devin/skills/tiptap/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tiptap -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about tiptap
How do I install tiptap in Claude Code?
Run npx skills add oakoss/agent-skills --skill tiptap -a claude-code. The skill file is at ~/.claude/skills/tiptap/SKILL.md.
What does tiptap do?
It guides React editor development with Tiptap, covering extensions, server rendering, image uploads, styling, and collaboration.
What should I change for Y.js collaboration?
Disable undo and redo in StarterKit with undoRedo: false. That is the configuration key used for this in Tiptap v3.
Source text
SKILL.md · MIT
---
name: tiptap
description: 'Builds rich text editors with Tiptap, a headless ProseMirror-based editor framework for React with Tailwind v4 support. Covers SSR-safe setup, image uploads, prose styling, collaborative editing, and markdown support. Use when adding a rich text editor, configuring Tiptap extensions, handling image uploads in editors, or setting up collaborative editing with Y.js. Use for tiptap, rich text, editor, prosemirror, react, tailwind.'
license: MIT
metadata:
author: oakoss
version: '1.0'
source: 'https://tiptap.dev/docs'
user-invocable: false
---
# Tiptap Rich Text Editor
## Overview
Tiptap is a headless rich text editor built on ProseMirror, providing a modular extension system for React applications. It supports React 19, Tailwind v4, and SSR frameworks like Next.js. Use when building blog editors, comment systems, documentation tools, or Notion-like collaborative apps. Do NOT use with Create React App (CRA is incompatible with Tiptap v3 ESM module structure; use Vite instead).
## Quick Reference
| Pattern | API / Key Point |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Create editor | `useEditor({ extensions: [StarterKit], immediatelyRender: false })` |
| Render editor | `<EditorContent editor={editor} />` |
| Prose styling | Add `className="prose dark:prose-invert max-w-none"` to container |
| Configure StarterKit | `StarterKit.configure({ heading: { levels: [1, 2, 3] } })` |
| Disable undo/redo | `StarterKit.configure({ undoRedo: false })` (required for Y.js collab) |
| Image upload | Set `allowBase64: false`, use upload handler with URL replacement |
| Markdown support | `import { Markdown } from '@tiptap/markdown'` (official, open-source) |
| shadcn component | `npx shadcn@latest add https://raw.githubusercontent.com/Aslam97/shadcn-minimal-tiptap/main/registry/block-registry.json` |
| Null guard | `useEditor()` returns `Editor \| null` — guard before calling methods |
## Core Dependencies
| Package | Purpose |
| ------------------------- | ---------------------------------------------------------- |
| `@tiptap/react` | React integration (React 19 supported since v2.10.0) |
| `@tiptap/starter-kit` | Bundled extensions: marks, nodes, and functionality |
| `@tiptap/pm` | ProseMirror peer dependency (required, not auto-installed) |
| `@tailwindcss/typography` | Prose styling for headings, lists, links |
## StarterKit v3 Contents
| Category | Included |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Marks | Bold, Italic, Strike, Code, Link (v3), Underline (v3) |
| Nodes | Document, Paragraph, Text, Heading, BulletList, OrderedList, ListItem, Blockquote, CodeBlock, HorizontalRule, HardBreak |
| Functionality | Undo/Redo, Dropcursor, Gapcursor, ListKeymap (v3), TrailingNode (v3) |
## Common Additional Extensions
| Extension | Package | Use Case |
| ----------------- | --------------------------------------- | ------------------------------------ |
| Image | `@tiptap/extension-image` | Image support with resize |
| Color | `@tiptap/extension-color` | Text color (requires TextStyle) |
| Typography | `@tiptap/extension-typography` | Smart quotes, dashes, ellipsis |
| Placeholder | `@tiptap/extension-placeholder` | Placeholder text (requires CSS) |
| Table | `@tiptap/extension-table` | Table support (+ Row, Cell, Header) |
| TaskList | `@tiptap/extension-task-list` | Checkbox task lists |
| CodeBlockLowlight | `@tiptap/extension-code-block-lowlight` | Syntax-highlighted code |
| Collaboration | `@tiptap/extension-collaboration` | Real-time multi-user editing (Y.js) |
| Markdown | `@tiptap/markdown` | Bidirectional markdown (open-source) |
## Common Mistakes
| Mistake | Fix |
| ----------------------------------------- | ------------------------------------------------------------------ |
| Missing `immediatelyRender: false` | Add to `useEditor()` config — required for SSR/Next.js |
| No `prose` classes on editor container | Add `className="prose prose-sm dark:prose-invert max-w-none"` |
| Images stored as base64 | Set `allowBase64: false`, use upload handler with URL replacement |
| Using EditorProvider + useEditor together | Choose one — EditorProvider wraps useEditor internally |
| Undo/Redo enabled with Collaboration | Set `undoRedo: false` in StarterKit when using Y.js |
| ProseMirror version conflicts | Add `resolutions` for prosemirror-model/view/state in package.json |
| Using Create React App | Switch to Vite — CRA incompatible with v3 ESM modules |
| Not checking `editor` for null | `useEditor()` returns `Editor \| null` — guard before use |
| Using `history: false` for collab | Config key renamed to `undoRedo` in v3 |
| Importing `@tiptap/extension-markdown` | Correct package is `@tiptap/markdown` |
## Delegation
- **Tailwind styling**: see `tailwind` skill
- **Form integration**: see `tanstack-form` skill
## References
- [Setup and Configuration](references/setup.md)
- [Extensions Catalog](references/extensions.md)
- [Image Upload](references/image-upload.md)
- [Patterns](references/patterns.md)
- [Known Issues and Errors](references/known-issues.md)
- [Prose Styling](references/prose-styling.md)
© oakoss · MIT · oakoss/agent-skills