fix: default to rendering the editor immediately, while staying backward compatible

.changeset/fresh-chefs-agree.md

@@ -0,0 +1,67 @@
+---
+"@tiptap/react": patch
+---
+
+We've heard a number of complaints around the performance of our React integration, and we finally have a solution that we believe will satisfy everyone. We've made a number of optimizations to how the editor is rendered, as well give you more control over the rendering process.
+
+Here is a summary of the changes and how you can take advantage of them:
+
+- SSR rendering was holding back our ability to have an editor instance on first render of `useEditor`. We've now made the default behavior to render the editor immediately on the client. This behavior can be controlled with the new `immediatelyRender` option which when set to `false` will defer rendering until the second render (via a useEffect), this should only be used when server-side rendering.
+- The default behavior of the useEditor hook is to re-render the editor on every editor transaction. Now with the `shouldRerenderOnTransaction` option, you can disable this behavior to optimize performance. Instead, to access the new editor state, you can use the `useEditorState` hook.
+- `useEditorState` this new hook allows you to select from the editor instance any state you need to render your UI. This is useful when you want to optimize performance by only re-rendering the parts of your UI that need to be updated.
+
+Here is a usage example:
+
+```jsx
+  const editor = useEditor({
+    /**
+     * This option gives us the control to enable the default behavior of rendering the editor immediately.
+     */
+    immediatelyRender: true,
+    /**
+     * This option gives us the control to disable the default behavior of re-rendering the editor on every transaction.
+     */
+    shouldRerenderOnTransaction: false,
+    extensions: [StarterKit],
+    content: `
+    <p>
+      A highly optimized editor that only re-renders when it’s necessary.
+    </p>
+    `,
+  })
+
+  /**
+   * This hook allows us to select the editor state we want to use in our component.
+   */
+  const currentEditorState = useEditorState({
+    /**
+     * The editor instance we want to use.
+     */
+    editor,
+    /**
+     * This selector allows us to select the data we want to use in our component.
+     * It is evaluated on every editor transaction and compared to it's previously returned value.
+     * You can return any data shape you want.
+     */
+    selector: ctx => ({
+      isBold: ctx.editor.isActive('bold'),
+      isItalic: ctx.editor.isActive('italic'),
+      isStrike: ctx.editor.isActive('strike'),
+    }),
+    /**
+     * This function allows us to customize the equality check for the selector.
+     * By default it is a `===` check.
+     */
+    equalityFn: (prev, next) => {
+      // A deep-equal function would probably be more maintainable here, but, we use a shallow one to show that it can be customized.
+      if (!next) {
+        return false
+      }
+      return (
+        prev.isBold === next.isBold
+        && prev.isItalic === next.isItalic
+        && prev.isStrike === next.isStrike
+      )
+    },
+  })
+```

demos/src/Examples/Performance/React/index.jsx

@@ -0,0 +1,130 @@
+import './styles.scss'
+
+import {
+  BubbleMenu, EditorContent, useEditor, useEditorState,
+} from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import React from 'react'
+
+function EditorInstance({ shouldOptimizeRendering }) {
+  const countRenderRef = React.useRef(0)
+
+  countRenderRef.current += 1
+
+  const editor = useEditor({
+    /**
+     * This option gives us the control to enable the default behavior of rendering the editor immediately.
+     */
+    immediatelyRender: true,
+    /**
+     * This option gives us the control to disable the default behavior of re-rendering the editor on every transaction.
+     */
+    shouldRerenderOnTransaction: !shouldOptimizeRendering,
+    extensions: [StarterKit],
+    content: `
+    <p>
+      A highly optimized editor that only re-renders when it’s necessary.
+    </p>
+    `,
+  })
+  /**
+   * This hook allows us to select the editor state we want to use in our component.
+   */
+  const currentEditorState = useEditorState({
+    /**
+     * The editor instance we want to use.
+     */
+    editor,
+    /**
+     * This selector allows us to select the data we want to use in our component.
+     * It is evaluated on every editor transaction and compared to it's previously returned value.
+     */
+    selector: ctx => ({
+      isBold: ctx.editor.isActive('bold'),
+      isItalic: ctx.editor.isActive('italic'),
+      isStrike: ctx.editor.isActive('strike'),
+    }),
+    /**
+     * This function allows us to customize the equality check for the selector.
+     * By default it is a `===` check.
+     */
+    equalityFn: (prev, next) => {
+      // A deep-equal function would probably be more maintainable here, but, we use a shallow one to show that it can be customized.
+      if (!next) {
+        return false
+      }
+      return (
+        prev.isBold === next.isBold
+        && prev.isItalic === next.isItalic
+        && prev.isStrike === next.isStrike
+      )
+    },
+  })
+
+  return (
+    <>
+      <div className="control-group">
+        <div>Number of renders: <span id="render-count">{countRenderRef.current}</span></div>
+      </div>
+      {currentEditorState && (
+        <BubbleMenu className="bubble-menu" tippyOptions={{ duration: 100 }} editor={editor}>
+          <button
+            onClick={() => editor.chain().focus().toggleBold().run()}
+            className={currentEditorState.isBold ? 'is-active' : ''}
+          >
+            Bold
+          </button>
+          <button
+            onClick={() => editor.chain().focus().toggleItalic().run()}
+            className={currentEditorState.isItalic ? 'is-active' : ''}
+          >
+            Italic
+          </button>
+          <button
+            onClick={() => editor.chain().focus().toggleStrike().run()}
+            className={currentEditorState.isStrike ? 'is-active' : ''}
+          >
+            Strike
+          </button>
+        </BubbleMenu>
+      )}
+      <EditorContent editor={editor} />
+    </>
+  )
+}
+
+export default () => {
+  const [shouldOptimizeRendering, setShouldOptimizeRendering] = React.useState(true)
+
+  return (
+    <>
+      <div className="control-group">
+        <div className="switch-group">
+          <label>
+            <input
+              type="radio"
+              name="option-switch"
+              onChange={() => {
+                setShouldOptimizeRendering(true)
+              }}
+              checked={shouldOptimizeRendering === true}
+            />
+            Optimize rendering
+          </label>
+          <label>
+            <input
+              type="radio"
+              name="option-switch"
+              onChange={() => {
+                setShouldOptimizeRendering(false)
+              }}
+              checked={shouldOptimizeRendering === false}
+            />
+            Render every transaction (default behavior)
+          </label>
+        </div>
+      </div>
+      <EditorInstance shouldOptimizeRendering={shouldOptimizeRendering} />
+    </>
+  )
+}

demos/src/Examples/Performance/React/index.spec.js

@@ -0,0 +1,12 @@
+context('/src/Examples/Performance/React/', () => {
+  beforeEach(() => {
+    cy.visit('/src/Examples/Performance/React/')
+  })
+
+  it('should have a working tiptap instance', () => {
+    cy.get('.tiptap').then(([{ editor }]) => {
+      // eslint-disable-next-line
+      expect(editor).to.not.be.null
+    })
+  })
+})

demos/src/Examples/Performance/React/styles.scss

@@ -0,0 +1,91 @@
+/* Basic editor styles */
+.tiptap {
+  :first-child {
+    margin-top: 0;
+  }
+
+  /* List styles */
+  ul, 
+  ol {
+    padding: 0 1rem;
+    margin: 1.25rem 1rem 1.25rem 0.4rem;
+
+    li p {
+      margin-top: 0.25em;
+      margin-bottom: 0.25em;
+    }
+  }
+
+  /* Heading styles */
+  h1, 
+  h2, 
+  h3, 
+  h4, 
+  h5, 
+  h6 {
+    line-height: 1.1;
+    margin-top: 2.5rem;
+    text-wrap: pretty;
+  }
+
+  h1, 
+  h2 {
+    margin-top: 3.5rem;
+    margin-bottom: 1.5rem;
+  }
+
+  h1 { 
+    font-size: 1.4rem; 
+  }
+
+  h2 { 
+    font-size: 1.2rem; 
+  }
+
+  h3 { 
+    font-size: 1.1rem; 
+  }
+
+  h4, 
+  h5, 
+  h6 { 
+    font-size: 1rem; 
+  }
+
+  /* Code and preformatted text styles */
+  code {
+    background-color: var(--purple-light);
+    border-radius: 0.4rem;
+    color: var(--black);
+    font-size: 0.85rem;
+    padding: 0.25em 0.3em;
+  }
+
+  pre {
+    background: var(--black);
+    border-radius: 0.5rem;
+    color: var(--white);
+    font-family: 'JetBrainsMono', monospace;
+    margin: 1.5rem 0;
+    padding: 0.75rem 1rem;
+
+    code {
+      background: none;
+      color: inherit;
+      font-size: 0.8rem;
+      padding: 0;
+    }
+  }
+
+  blockquote {
+    border-left: 3px solid var(--gray-3);
+    margin: 1.5rem 0;
+    padding-left: 1rem;
+  }
+
+  hr {
+    border: none;
+    border-top: 1px solid var(--gray-2);
+    margin: 2rem 0;
+  }
+}