Skip to content

Fix Mirador build issues on main and 10.x - #6171

Open
tdonohue wants to merge 2 commits into
DSpace:mainfrom
tdonohue:fix_mirador_eresolve_warnings
Open

Fix Mirador build issues on main and 10.x#6171
tdonohue wants to merge 2 commits into
DSpace:mainfrom
tdonohue:fix_mirador_eresolve_warnings

Conversation

@tdonohue

@tdonohue tdonohue commented Sep 1, 2026

Copy link
Copy Markdown
Member

Description

This PR fixes issues that have recently appeared on the main and dspace-10_x branch regarding install/build warnings related to Mirador inconsistencies/incompatibilities.

There's two main issues that are fixed here:

  1. A regular npm install will show a number of ERESOLVE warnings that look like this. These warnings all relate to Mirador and the mirador-share-plugin
    npm warn While resolving: notistack@3.0.2
    npm warn Found: react@16.14.0
    npm warn node_modules/react
    npm warn   peer react@"^16.8.0 || ^17.0.0" from @material-ui/core@4.12.4
    npm warn   node_modules/@material-ui/core
    npm warn     peer @material-ui/core@"^4.0.0" from @material-ui/icons@4.11.3
    npm warn     node_modules/@material-ui/icons
    npm warn     4 more (@material-ui/lab, mirador, mirador-dl-plugin, mirador-share-plugin)
    npm warn   33 more (@material-ui/icons, @material-ui/lab, ...)
    npm warn
    npm warn Could not resolve dependency:
    npm warn peer react@"^17.0.0 || ^18.0.0 || ^19.0.0" from notistack@3.0.2
    npm warn node_modules/notistack
    npm warn   notistack@"^3.0.1" from mirador-share-plugin@0.16.0
    npm warn   node_modules/mirador-share-plugin
    npm warn
    npm warn Conflicting peer dependency: react@19.2.8
    npm warn node_modules/react
    npm warn   peer react@"^17.0.0 || ^18.0.0 || ^19.0.0" from notistack@3.0.2
    npm warn   node_modules/notistack
    npm warn     notistack@"^3.0.1" from mirador-share-plugin@0.16.0
    npm warn     node_modules/mirador-share-plugin
    npm warn ERESOLVE overriding peer dependency
    npm warn While resolving: notistack@3.0.2
    npm warn Found: react-dom@16.14.0
    npm warn node_modules/react-dom
    npm warn   peer react-dom@"^16.8.0 || ^17.0.0" from @material-ui/core@4.12.4
    npm warn   node_modules/@material-ui/core
    npm warn     peer @material-ui/core@"^4.0.0" from @material-ui/icons@4.11.3
    npm warn     node_modules/@material-ui/icons
    npm warn     4 more (@material-ui/lab, mirador, mirador-dl-plugin, mirador-share-plugin)
    npm warn   21 more (@material-ui/icons, @material-ui/lab, ...)
    npm warn
    npm warn Could not resolve dependency:
    npm warn peer react-dom@"^17.0.0 || ^18.0.0 || ^19.0.0" from notistack@3.0.2
    npm warn node_modules/notistack
    npm warn   notistack@"^3.0.1" from mirador-share-plugin@0.16.0
    npm warn   node_modules/mirador-share-plugin
    npm warn
    npm warn Conflicting peer dependency: react-dom@19.2.8
    npm warn node_modules/react-dom
    npm warn   peer react-dom@"^17.0.0 || ^18.0.0 || ^19.0.0" from notistack@3.0.2
    npm warn   node_modules/notistack
    npm warn     notistack@"^3.0.1" from mirador-share-plugin@0.16.0
    npm warn     node_modules/mirador-share-plugin
    
  2. Second, the Mirador build process (npm run build:mirador) doesn't work for Node 22.20+. It will throw an immediate error that looks like this:
    [webpack-cli] Failed to load 'C:\dspace-angular\webpack\webpack.mirador.config.ts' config
    [webpack-cli] ReferenceError: require is not defined in ES module scope, you can use import instead
       at file:///C:/dspace-angular/webpack/webpack.mirador.config.ts:4:27
       at ModuleJobSync.runSync (node:internal/modules/esm/module_job:458:37)
       at ModuleLoader.importSyncForRequire (node:internal/modules/esm/loader:435:47)
       at loadESMFromCJS (node:internal/modules/cjs/loader:1537:24)
       at Module._compile (node:internal/modules/cjs/loader:1688:5)
       at Module.m._compile (C:\dspace-angular\node_modules\ts-node\src\index.ts:858:23)
       at node:internal/modules/cjs/loader:1839:10
       at Object.require.extensions.<computed> [as .ts] (C:\dspace-angular\node_modules\ts-node\src\index.ts:861:12)
       at Module.load (node:internal/modules/cjs/loader:1441:32)
       at Function._load (node:internal/modules/cjs/loader:1263:12)
    

There's two fixes in this PR:

  1. To fix the npm install issues, I've pinned react and react-dom to 16.14.0 and notistack to 1.0.10 in the overrides section of the package.json.
    • Pinning react and react-dom ensures that we are using the exact version of React that Mirador v3 is expecting
    • Pinning notistack is actually a downgrade of the notistack version used by mirador-share-plugin. But, this older version of notistack is compatible with React v16. (I've also tested it manually and verified this doesn't impact the mirador-share-plugin behavior...the share button still works fine from within Mirador)
    • ALL of these pinned versions should be considered temporary until we upgrade to Mirador v4 (see Upgrade to Mirador plugin v4.0.0 for IIIF #5443), but that seems like a larger effort.
  2. To fix the npm run build:mirador error, I've updated that script in package.json to align with the npm run build:prod script by using cross-env. That fixes the build error.

NOTE: This needs to be minimally backported to 10.x. It is possible that the npm install fix may also need to be backported further (I haven't yet analyzed if 9.x sees these same warnings. I suspect it likely does since the warnings come from using Mirador v3 with more modern dependencies elsewhere and v9 dependencies are similar enough to 10.x and main).

NOTE 2: This PR also MIGHT solve dependabot issues we are seeing in recent PRs like #6161. That's where this work all started...but the exact process that dependabot uses to create new PRs is a bit mysterious to me still. So, it may not be a complete solution.

Instructions for Reviewers

  • Review code changes
  • Try running npm install. Verify you no longer see the above ERESOLVE warnings
  • Try running npm run build:mirador (especially with Node v22.20+) and verify the build process now succeeds. Previously it failed immediately.
  • Optionally deploy & test IIIF integration with Mirador. (NOTE: I've already tested that the IIIF functionality still works with these changes in place, and the mirador-share-plugin still works to allow you to copy IIIF manifest information to share.)

AI Disclosure

I used Claude Code to help determine the source of both issues. Initially, I was trying to solve the first issue (npm install bug), and when I went to test the solution, I ran into the second issue. While the AI initially gave some incomplete, inaccurate advice for the ERESOLVE errors, I was able to build the solution to the first issue (npm install) via these discussions. The second issue was pinpointed directly by AI, but I fully tested the solution to ensure IIIF still functions properly.

This PR description is fully written by me & all code fully reviewed & tested by me (including re-deploying and verifying that Mirador and IIIF integration work as expected).

…ese all need to be pinned to versions that are compatible with Mirador v3.
… to use "cross-env" to work with later versions of Node (especially v22.20+)
@tdonohue tdonohue added code task 1 APPROVAL pull request only requires a single approval to merge integration: IIIF Related to International Image Interoperability Framework (IIIF) support port to dspace-10_x This PR needs to be ported to `dspace-10_x` branch for next bug-fix release labels Sep 1, 2026
@tdonohue tdonohue moved this to 🙋 Needs Reviewers Assigned in DSpace 11.0 Release Sep 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

1 APPROVAL pull request only requires a single approval to merge code task integration: IIIF Related to International Image Interoperability Framework (IIIF) support port to dspace-10_x This PR needs to be ported to `dspace-10_x` branch for next bug-fix release

Projects

Status: 🙋 Needs Reviewers Assigned

Development

Successfully merging this pull request may close these issues.

1 participant