Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill tiptap -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/tiptap/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/tiptap/

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

Similar skills

All skills for Frontend and UI →

From the same set106

The whole set →

Project sponsors

Companies that keep this analytics open