[pull] main from ueberdosis:main

.changeset/fix-react-respect-immediately-render-on-next.md

@@ -0,0 +1,5 @@
+---
+"@tiptap/react": patch
+---
+
+Respect explicit `immediatelyRender: true` in client-side Next.js. Previously, when running under Next.js (`window.next` present), the `immediatelyRender` option was forced to `false` even when the user explicitly passed `true`, breaking client-only Next.js apps that rely on the editor existing on the first render. The hook now only forces `false` when actual SSR is detected (`typeof window === 'undefined'`), or when running under Next.js with no explicit value.

packages/react/src/useEditor.ts

@@ -93,12 +93,20 @@ class EditorInstanceManager {
   }
 
   private getInitialEditor() {
-    let immediatelyRender = this.options.current.immediatelyRender ?? true
+    const explicit = this.options.current.immediatelyRender
+    let immediatelyRender = explicit ?? true
 
-    if (immediatelyRender && (isSSR || isNext)) {
+    if (isSSR) {
+      if (immediatelyRender && isDev) {
+        console.warn('SSR detected. `immediatelyRender` has been set to false to avoid hydration mismatches')
+      }
+      immediatelyRender = false
+    } else if (isNext && explicit === undefined) {
       immediatelyRender = false
       if (isDev) {
-        console.warn('SSR detected. `immediatelyRender` has been set to false to avoid hydration mismatches')
+        console.warn(
+          'Next.js detected. `immediatelyRender` defaults to false to avoid hydration mismatches. Pass `immediatelyRender: true` explicitly if you are rendering the editor only on the client.',
+        )
       }
     }