Content Check Performance in Large Collaborative Documents

[philmetzger]

The problem

I’m working on a collaborative writing app where some users create very large documents. One document that triggered this investigation was around 500k words.

Typing in that document was extremely laggy. Profiling showed the main cost came from enabling TipTap Collaboration’s content check:

enableContentCheck: true

The Collaboration extension registers a doc.on('beforeTransaction') handler that, on every Yjs transaction, converts the entire Y.XmlFragment to JSON, rebuilds the full ProseMirror document, and validates it:

// @tiptap/extension-collaboration (simplified)
yDocument.on('beforeTransaction', () => {
  const json = yXmlFragmentToProsemirrorJSON(fragment)
  editor.schema.nodeFromJSON(json).check() // O(document size)
})

“Every Yjs transaction” includes every local keystroke and every received remote update. In a 500k-word document, that meant hundreds of milliseconds of full-document validation per keystroke, plus heavy GC pressure from repeatedly allocating full JSON and ProseMirror node trees. I measured around 15 seconds of GC per 10 seconds of typing, making the editor unusable.

What I observed

A few things stood out during the investigation:

1. The check seems unable to prevent invalid content. It runs in beforeTransaction, so it validates the pre-update document state. Yjs handlers also cannot veto a transaction, since return values are ignored. So this appears to be detection/reporting only.

2. Local transactions should already be valid. Content produced by the local editor should be schema-valid by construction, because ProseMirror enforces the schema when building transactions. The real risk seems to be content entering through Yjs externally, such as remote peers, server-side restores, or version-skewed clients.

3. The non-deprecated converter does not work for this use case. yXmlFragmentToProsemirrorJSON is deprecated in favor of yXmlFragmentToProseMirrorRootNode, but the replacement silently drops schema-unknown nodes, which defeats validation. The deprecated JSON converter is the only route I found that lets nodeFromJSON().check() actually see invalid content.

4. enableContentCheck also changes setContent behavior. In @tiptap/core 2.27.1, errorOnInvalidContent in setContent / insertContentAt defaults to editor.options.enableContentCheck. Turning enableContentCheck off also makes invalid setContent input stop throwing. Instead, createNodeFromContent warns, returns empty content, and tr.replaceWith can silently wipe the document. I had to explicitly pass { errorOnInvalidContent: true } at import call sites.

My replacement

I removed enableContentCheck and added a small extension that keeps the same detection/reporting behavior, but only validates when it can matter.

It:

• observes only the shared content fragment with fragment.observeDeep
• ignores unrelated Y.Doc maps like comments/settings
• skips local ProseMirror → Yjs transactions using ySyncPluginKey
• skips Y.UndoManager transactions
• debounces validation with leading + trailing execution at 1 second
• validates once in onBeforeCreate to catch corrupt documents at load

import { Extension } from '@tiptap/core'
import type { Schema } from '@tiptap/pm/model'
import debounce from 'lodash/debounce'
import { ySyncPluginKey, yXmlFragmentToProsemirrorJSON } from 'y-prosemirror'
import * as Y from 'yjs'

export function shouldValidateTransaction(origin: unknown): boolean {
  if (origin === ySyncPluginKey) return false
  if (origin instanceof Y.UndoManager) return false

  return true
}

export function validateFragmentContent(schema: Schema, fragment: Y.XmlFragment): void {
  const json = yXmlFragmentToProsemirrorJSON(fragment)
  const content: unknown = json.content

  if (!Array.isArray(content) || content.length === 0) return

  schema.nodeFromJSON(json).check()
}

export const ContentIntegrityCheck = Extension.create({
  name: 'contentIntegrityCheck',

  addOptions() {
    return {
      fragment: null,
      onContentError: null,
    }
  },

  onBeforeCreate() {
    const { fragment, onContentError } = this.options
    const doc = fragment?.doc

    if (!fragment || !doc) return

    const validateAndReport = () => {
      if (doc.isDestroyed) return

      try {
        validateFragmentContent(this.editor.schema, fragment)
      } catch (error) {
        onContentError?.({
          error: error instanceof Error ? error : new Error(String(error)),
          disableCollaboration: () => doc.destroy(),
        })
      }
    }

    const debounced = debounce(validateAndReport, 1000, {
      leading: true,
      trailing: true,
    })

    const onFragmentChanged = (_events, transaction: Y.Transaction) => {
      if (!shouldValidateTransaction(transaction.origin)) return

      debounced()
    }

    fragment.observeDeep(onFragmentChanged)

    this.storage.detach = () => {
      debounced.cancel()
      fragment.unobserveDeep(onFragmentChanged)
    }

    validateAndReport()
  },

  onDestroy() {
    this.storage.detach?.()
  },
})

Important detail: use onBeforeCreate, not onCreate

The initial validation has to run in onBeforeCreate.

During view binding, y-prosemirror can silently delete nodes it cannot render. Specifically, createNodeFromYElement catches the error and removes the node under the ySyncPluginKey origin.

So by onCreate, a corrupt fragment may already look valid, and the data loss goes unreported. I have an integration test showing that onCreate is too late.

Result

Typing in the 500k-word document went from unusable back to normal.

I believe this keeps the same corruption detection coverage, and possibly improves it, because it catches corrupt-at-load documents before binding can mutate them.

Issues I can think of

1. Detection is delayed by up to ~1s
2. Silent repairs can hide corruption

Questions for the TipTap team

1. What are the current solutions for long documents?
2. What are your thoughts on the solution above?
3. Have I overlooked something?

p.s. Im rather new to tiptap ecosystem so go easy :)

[MILLERMARRU]

Your onBeforeCreate finding is right, and it matches how the built-in path is documented too, onContentError receives { editor, error, disableCollaboration }, exactly the shape you're replicating, so your custom extension isn't reinventing the contract, it's re-implementing the same one at a lower level to get control over when validation runs.

One difference worth reconsidering: the official disableCollaboration() helper only removes the Collaboration extension, it doesn't touch the underlying Y.Doc. Your version calls doc.destroy() directly, which is more final. Once destroyed, that document object can't be reused if you later want to inspect it (for a repair tool, or to see what content survived) or reconnect after a transient corruption rather than a real one. Swapping in the same disableCollaboration pattern, editor.setEditable(false) plus removing just the extension rather than destroying the doc, would give you the same "stop syncing bad content immediately" outcome without foreclosing on recovery.

On the debounce window: 1 second is a reasonable default, but since you already have onBeforeCreate catching load-time corruption (the case that matters most, since that's the one that can get silently repaired by y-prosemirror before you'd otherwise notice), the ongoing debounced check is really just a safety net for corruption introduced by a buggy peer mid-session. I'd keep it, but I wouldn't tighten it much below 1s chasing faster detection. The cost is back on the table you already measured (GC pressure), and a corrupt remote update is going to keep re-triggering the check on every subsequent transaction anyway until someone notices, so the marginal detection latency isn't doing much work.

This looks like a solid replacement for enableContentCheck as-is, worth posting as an issue/PR against the extension itself given how sharp the perf cliff is for large documents. That seems like something other collaboration users would hit and not think to profile their way out of.