Has anyone encountered a "ReferenceError: document is not defined" when using Annotorious 3.x with OpenSeaDragon and Next.js?

[Songhao-LI]

I'm using the following versions in my project:

Next.js: ^14.2.13
React: 18.2.0
@annotorious/react: ^3.0.11
@annotorious/openseadragon: ^3.0.11
When I try to render the page, I encounter the following error during server-side rendering (SSR):

⨯ ReferenceError: document is not defined
at C:\Users\lsoho\Git\MyProject\node_modules\openseadragon\build\openseadragon\openseadragon.js:970:29
at C:\Users\lsoho\Git\MyProject\node_modules\openseadragon\build\openseadragon\openseadragon.js:973:6
at Object. (C:\Users\lsoho\Git\MyProject\node_modules\openseadragon\build\openseadragon\openseadragon.js:1071:2)
at Module._compile (node:internal/modules/cjs/loader:1369:14)
at Module._extensions..js (node:internal/modules/cjs/loader:1427:10)
at Module.load (node:internal/modules/cjs/loader:1206:32)
at Module._load (node:internal/modules/cjs/loader:1022:12)
at cjsLoader (node:internal/modules/esm/translators:366:17)
at ModuleWrap. (node:internal/modules/esm/translators:315:7)
at ModuleJob.run (node:internal/modules/esm/module_job:222:25)
at async ModuleLoader.import (node:internal/modules/esm/loader:323:24)

And here's my Code:

When I init a new Next.js project without any other packages, I still meet the issue

[rsimon]

Yes, I have seen the problem.

First: make absolutely sure that any OpenSeadragon- or Annotorious-related code runs only in the browser, never in SSR!

Even then: unfortunately, OpenSeadragon does seem to access document on the global level, even before initializing the viewer. Which means that this error can happen (on an SSR-based framework) as soon as you import OpenSeadragon.

To repeat: this is not caused by Annotorious, but OpenSeadragon (see the error message). It happens as soon as OpenSeadragon gets imported as a dependency. (Note that even if you don't import OpenSeadragon yourself, it gets imported as a transitive dependency as soon as you import @annotorious/openseadragon or @annotorious/react.)

Below is how I worked around this limitation in an Astro project, using an async import. However I believe that Next has better utilities to "mark" libraries that only work in the browser and skip importing them in SSR accordingly.

https://github.com/annotorious/annotorious-website/blob/main/src/components/OpenSeadragonExample.tsx#L11-L18

const {
    Annotorious,
    OpenSeadragonAnnotator,
    OpenSeadragonViewer,
    ShapeType,
    useAnnotator,
    useSelection
  } = await import('@annotorious/react');

[Songhao-LI]

Would you mind if sharing the code how you implement this part so as to help me better understand how to use annotorious 3.x. @rsimon

I am having an issue where I can't start drawing, even when holding the Shift key

[rsimon]

You're missing the CSS stylesheet. See step 2 of the step-by-step guide here: https://annotorious.dev/react/openseadragon-iiif/

Note that you don't need to press the Shift key with Annotorious v3.

The code for the docs Website is here: https://github.com/annotorious/annotorious-website/blob/main/src/components/OpenSeadragonExample.tsx

[Songhao-LI]

Sorry for asking too much!! Have you ever encountered the error when packaging the project? @rsimon

Everything works fine when I run the project locally, and I've already used dynamic imports to resolve a previous issue.
However, when packaging the project, I encountered this error:

And here's how I import the packages:

[Songhao-LI]

solved!!

[Songhao-LI]

But it seems like we still need to modify the library by adding this, it there any better solutions? @rsimon

[Clasen00]

Solved this isue like that:

const PreparationCanvas = dynamic(
  () =>
    import('../PreparationCanvas/PreparationCanvas').then(
      (mod) => mod.PreparationCanvas
    ),
  { ssr: false }
);

where PreparationCanvas is my Annotorious component. No problem at all