tiptap/docs/src/docPages/overview/upgrade-guide.md

# Upgrade Guide

## toc

## Reasons to upgrade to tiptap 2.x
Yes, it’s tedious work to upgrade your favorite text editor to a new API, but we made sure you’ve got enough reasons to upgrade to the newest version

* Autocompletion in your IDE (thanks to TypeScript)
* Amazing documentation with 100+ pages
* Active development, new features in the making
* Tons of new extensions planned
* Well-tested code base

## Upgrading from 1.x to 2.x
The new API will look pretty familiar too you, but there are a ton of changes though. To make the upgrade a little bit easier, here is everything you need to know:

### Upgrade to Vue.js 3
…

### Explicitly register the Document, Text and Paragraph extensions
tiptap 1 tried to hide a few required extensions from you with the default setting `useBuiltInExtensions: true`. That setting has been removed and you’re required to import all extensions. Be sure to explicitly import at least the [Document](/api/nodes/document), [Paragraph](/api/nodes/paragraph) and [Text](/api/nodes/text) extensions.

```js
import Document from '@tiptap/extension-document'
import Paragraph from '@tiptap/extension-paragraph'
import Text from '@tiptap/extension-text'

new Editor({
  extensions: [
      Document(),
      Paragraph(),
      Text(),
      // all your other extensions
  ]
})
```

### New document type
~~**We renamed the default `Document` type from `doc` to `document`.** To keep it like that, use your own implementation of the `Document` node or migrate the stored JSON to use the new name.~~

### New extension API
In case you’ve built some custom extensions for your project, you’re required to rewrite them to fit the new API. No worries, you can keep a lot of your work though. The `schema`, `commands`, `keys`, `inputRules` and `pasteRules` all work like they did before. It’s just different how you register them.

```js
import { createNode } from '@tiptap/core'

const CustomExtension = createNode({
  name: 'custom_extension'
  defaultOptions: {
    …
  },
  addAttributes() {
    …
  },
  parseHTML() {
    …
  },
  renderHTML({ node, attributes }) {
    …
  },
  addCommands() {
    …
  },
  addKeyboardShortcuts() {
    …
  },
  addInputRules() {
    …
  },
  // and more …
})
```

Don’t forget to call `create()` in the end! Read more about [all the nifty details building custom extensions](/guide/build-custom-extensions) in our guide.

### Renamed API methods
[We renamed a lot of commands](/api/commands), hopefully you can migrate to the new API with search & replace. Here is a list of what changed:

| Old method name | New method name |
| --------------- | --------------- |
| ~~`…`~~         | `…`             |

### Commands can be chained now

…

### .focus() isn’t called on every command anymore
We tried to hide the `.focus()` command from you with tiptap 1 and executed that on every other command. That led to issues in specific use cases, where you want to run a command, but don’t want to focus the editor. With tiptap 2.x you have to explicitly call the `focus()` and you probably want to do that in a lot of places. Here is an example:

```js
editor.chain().focus().bold().run()
```