Regression in 0.38: introduces import-time call to `document.createElement` which fails in non-browsers

[ianmacartney]

Describe the bug

Ever since 0.38.0, there is a dependency on decode-named-character-reference at import time for BlockNoteEditor, such that importing it causes Uncaught ReferenceError: document is not defined in environments where document doesn't exist, e.g. Convex functions. I also filed #2173 to track the broader ask of supporting serverless environments.

To Reproduce

get-convex/prosemirror-sync#187
clone the repo, then npm i && npm run dev - it should successfully deploy to Convex. After upgrading to 0.38, it fails.

Misc

• Node version:v20.19.5
• Package manager:npm
• Browser:non-browser environment (Convex.dev)
• I'm a sponsor and would appreciate if you could look into this sooner than later 💖

[ianmacartney]

It's possible that even without this, there is still an issue with tiptap v3 running on the server - I haven't dug in much beyond seeing this error

[nperez0111]

@ianmacartney, I'm unsure why you'd be getting this error, because according to their package.json, you should be importing the index.js file rather than the DOM version. Perhaps there is some module resolution you can set in your bundler?

Either way, we are using JSDom for mocking document methods. So that is unlikely to work in the runtime you are using anyway (and if it is perhaps, you can load it first?). And this is already tracked by another issue: #942

[ianmacartney]

Ah good catch, I'll put up a PR to that package - we (Convex) use "browser"as a fallback if "convex" isn't provided. Patching that package has it working.
Otherwise it's working fine - I just need the BlockNoteEditor constructor to get the pmSchema, which allows me to extract the full text to denormalize into a table for text search.
If the blocknote extensions -> tiptap extensions function could be factored out, I suspect I could avoid making the editor altogether.

[ianmacartney]

Thanks for the quick responses! btw there's a Convex component to add BlockNote / TipTap server-side sync using the PM OT protocol (instead of yjs): https://www.convex.dev/components/prosemirror-sync
Let me know if you want be involved / have any feedback.
It's used by Chef as one of the templates so folks can vibe-code blocknote-based apps e.g. Notion clones: chef.convex.dev

[nperez0111]

Ah good catch, I'll put up a PR to that package - we (Convex) use "browser"as a fallback if "convex" isn't provided. Patching that package has it working.

Oh interesting, I'm unsure what a sane default would be for you since the packages may just assume the environment.

Otherwise it's working fine - I just need the BlockNoteEditor constructor to get the pmSchema, which allows me to extract the full text to denormalize into a table for text search.

I saw this, honestly, I'd have just skipped the editor JSON -> prosemirror objects, and just walk the JSON & pull any text: string that is in there (that is essentially all that the textContent is doing for you anyway. This would work in both Tiptap JSON & BlockNote JSON.

If the blocknote extensions -> tiptap extensions function could be factored out, I suspect I could avoid making the editor altogether.

Eh, just creating an editor instance is actually pretty cheap. It won't touch any DOM functions until it is editor.mount'ed so it is safe on the server-side too.

[nperez0111]

Thanks for the quick responses! btw there's a Convex component to add BlockNote / TipTap server-side sync using the PM OT protocol (instead of yjs): convex.dev/components/prosemirror-sync Let me know if you want be involved / have any feedback. It's used by Chef as one of the templates so folks can vibe-code blocknote-based apps e.g. Notion clones: chef.convex.dev

Very cool, thanks for sharing. I'll have to take a deeper look later

[nperez0111]

I made a patch for updating the server-util to use any DOM shim, which hopefully will help with portability too: #2175

[ianmacartney]

Awesome, thank you. So it sounds like there's a couple paths forward:

1. If I can get that package patched, then folks can pin that newer version so the runtime document issue will allow importing BlockNoteEditor. This seems like a pre-requisite also for importing the server editor, since it in turn imports the BlockNoteEditor internally.
2. For text extraction, the schema can be skipped entirely with some json traversal. Maybe I can give folks a utility function to extract text server-side, so they don't have to copy-paste that.
3. For more nuanced server-side editing, the server editor is aiming to be more pluggable & make fewer assumptions about the environment. DOM shims seem like a great idea. Figuring out a jsdom path that works in our environment is also important - or just tell people that they need to use ServerBlockNoteEditor within our node environment. Which is ok but not ideal - they can't use it within a DB transaction (query or mutation) - and it's a bit slower to run since it's running in lambda.

The errors I get when trying to import ServerBlockNoteEditor right now look like this - jsdom using node APIs.

✘ [ERROR] Could not resolve "fs"

    node_modules/jsdom/lib/jsdom/browser/resources/resource-loader.js:2:19:
      2 │ const fs = require("fs");
        ╵                    ~~~~

  The package "fs" wasn't found on the file system but is built into node. Are you trying to bundle
  for node? You can use "platform: 'node'" to do that, which will remove this error.

✘ [ERROR] Could not resolve "url"

    node_modules/jsdom/lib/jsdom/browser/resources/resource-loader.js:3:34:
      3 │ const { fileURLToPath } = require("url");
        ╵                                   ~~~~~

  The package "url" wasn't found on the file system but is built into node. Are you trying to bundle
  for node? You can use "platform: 'node'" to do that, which will remove this error.

✘ [ERROR] Could not resolve "vm"

    node_modules/jsdom/lib/jsdom/browser/Window.js:2:19:
      2 │ const vm = require("vm");
        ╵                    ~~~~

  The package "vm" wasn't found on the file system but is built into node. Are you trying to bundle
  for node? You can use "platform: 'node'" to do that, which will remove this error.

✘ [ERROR] Could not resolve "http"

    node_modules/jsdom/lib/jsdom/living/helpers/agent-factory.js:2:21:

[nperez0111]

3. Yea, so it depends on what methods you end up using on the server whether you would need the shim at all, if you are doing something like only touching the schema, then it would not rely on a DOM implementation, but if you need something does things like HTML or markdown conversion, then JSDOM, or happy DOM, or even something like https://github.com/WebReflection/linkedom might work depending on what is accessed and their support.