Migrating from Tiptap 2 to 3

Tiptap v3 is a major update with breaking changes, but the migration process is quite simple. This guide will help you upgrade your Liveblocks project that uses Tiptap from version 2 to version 3.

Upgrade dependencies

First, you must uninstall all Tiptap and Liveblocks dependencies to avoid future version conflicts as we upgrade. This includes any extra Tiptap extensions you may have installed or anything else with a dependency on Tiptap.

AI-assisted upgrade

The easiest way to do this is to allow our AI assistant to generate the commands for you. Make sure you’re signed in, paste your package.json into the following input, and generate the commands.

Manual upgrade

If you’d like to upgrade manually, you need to run the npm command to uninstall all Tiptap and Liveblocks packages. Note that you are likely using more package than are listed here, such as Tiptap extensions.

$npm uninstall @tiptap/react @tiptap/starter-kit @liveblocks/client @liveblocks/react @liveblocks/react-ui @liveblocks/react-tiptap @liveblocks/node

Next re-install all Tiptap and Liveblocks packages. If you see a peer dependency issue during this install, you may have missed something during the previous uninstall step.

$npm install @tiptap/react@3 @tiptap/starter-kit@3 @liveblocks/client@latest @liveblocks/react@latest @liveblocks/react-ui@latest @liveblocks/react-tiptap@latest @liveblocks/node@latest

This will ensure that all packages are compatible with each other and prevent version conflicts.

Critical changes for Liveblocks users

While Tiptap 3 includes many changes, there are two particularly critical changes that affect Liveblocks integration:

1. StarterKit configuration change

Liveblocks provides its own undo/redo functionality for collaborative editing. In Tiptap 2, you disabled this by setting history: false in the StarterKit extension. In Tiptap 3, this option has been renamed to undoRedo:

const editor = useEditor({  extensions: [    StarterKit.configure({      undoRedo: false, // Previously: history: false    }),    // Other extensions...  ],});

2. Set immediatelyRender: false for SSR

If you're using server-side rendering (such as with Next.js), it's now more critical to set immediatelyRender: false in your editor configuration to prevent hydration issues:

const editor = useEditor(  {    immediatelyRender: false,    extensions: [      StarterKit.configure({        undoRedo: false,      }),      // Other extensions...    ],  },  []);

This ensures the editor doesn't render on the server, which can cause mismatches between server and client rendering.

Style Changes

If you have your own styles for collaboration cursors, the default CSS classes prefix changed from .collaboration-cursor to .collaboration-carets.

- .collaboration-cursor__caret {+ .collaboration-carets__caret {  /* Your caret styles */}
- .collaboration-cursor__label {+ .collaboration-carets__label {  /* Your label styles */}

Full migration guide

For a complete list of breaking changes and new features in Tiptap 3, refer to the official Tiptap upgrade guide.