Can't resolve '@theme/Unlisted' after update to Docusaurus 3.5.0

[Preston-Landers]

Describe the bug

First, thanks for the great plugin. After updating to Docusaurus 3.5.0, the build fails with:

Module not found: Error: Can't resolve '@theme/Unlisted' in '/home/planders/src/jx/jx-api-docs/node_modules/docusaurus-theme-openapi-docs/lib/theme/ApiItem/Layout'

Expected behavior

Compilation should continue to work.

Current behavior

Updated to Docusaurus 3.5.0 (from 3.4.0) with the following command:

yarn upgrade @docusaurus/core@latest @docusaurus/plugin-client-redirects@latest @docusaurus/preset-classic@latest @docusaurus/eslint-plugin@latest @docusaurus/module-type-aliases@latest @docusaurus/tsconfig@latest @docusaurus/types@latest

Then compilation fails with:

[ERROR] Client bundle compiled with errors therefore further build is impossible.
Module not found: Error: Can't resolve '@theme/Unlisted' in '/home/planders/src/jx/jx-api-docs/node_modules/docusaurus-theme-openapi-docs/lib/theme/ApiItem/Layout'

Steps to reproduce

1. Take existing working project with Docusaurus 3.4.0 and Docusaurus-Openapi-Docs 3.0.1.
2. Run the command above to update to Docusaurus 3.5.0
3. Run yarn build or equivalent to see the build failure.

Your Environment

• Version used: 3.0.1
• Environment name and version (e.g. Chrome 59, node.js 5.4, python 3.7.3): Node v20.16.0
• Operating System and version (desktop or mobile): Ubuntu 24.04
• Link to your project:

[sserrata]

Hi @Preston-Landers, seems to be an undocumented breaking change introduced here: https://github.com/facebook/docusaurus/pull/10376/files

[Devon-White]

I started working on a PR for this issue.

Upon upgrading the Docusaurus version, i tried two different approaches.

1st. I tried to swap the import path and continue to use the Unlisted component directly.
2nd. Swapped to using the ContentVisibility component and passing it the metadata gathered from the useDoc function.

Doing both of these approaches leaves me with the following error:

react-dom.development.js:28474 Uncaught Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined. You likely forgot to export your component from the file it's defined in, or you might have mixed up default and named imports.

Check the render method of `ApiItem`.
    at createFiberFromTypeAndProps (react-dom.development.js:28474:17)
    at createFiberFromElement (react-dom.development.js:28500:15)
    at reconcileSingleElement (react-dom.development.js:13987:23)
    at reconcileChildFibers (react-dom.development.js:14045:35)
    at reconcileChildren (react-dom.development.js:19182:28)
    at mountIndeterminateComponent (react-dom.development.js:20182:5)
    at beginWork (react-dom.development.js:21622:16)
    at HTMLUnknownElement.callCallback (react-dom.development.js:4165:14)
    at Object.invokeGuardedCallbackDev (react-dom.development.js:4214:16)
    at invokeGuardedCallback (react-dom.development.js:4278:31)
react-dom.development.js:18705 The above error occurred in the <ApiItem> component:

If i make the APItem Component just render in a simple div, the error stops.

I'm still fairly new to React in general, so I haven't been able to discover what the root cause of the issue its. I'll continue to mess around in hopes that I can solve the issue, but a more experienced Developer might be able to make light work of this. :)

Edit: Seems to be coming from the DocProvider? I went down the list of removing components until the error stop. So it seems to be somewhere related with the props.contents and how the DocProvider is handling APIItems?

[sserrata]

It's a fairly simple fix but may require breaking backward compatibility with prior releases.

[johnmcase]

Hi @Preston-Landers, seems to be an undocumented breaking change introduced here: https://github.com/facebook/docusaurus/pull/10376/files

If this is a breaking change in docusaurus should an issue be opened there for them to fix?

[sserrata]

If this is a breaking change in docusaurus should an issue be opened there for them to fix?

You could, but I doubt it would lead to a fix. Over the years, we've come to expect breaking changes to land every so often, as the semantic versioning doesn't apply to some internals. That said, I looked into it earlier today and it seems the fix will not be trivial after all.

The bigger question is, if the solution does in fact break backward compatibility should we bump our plugin to v4?

[santhoshmurthybk]

Will there be a fix rolled out for this?

[sserrata]

Hi everyone, I opened a PR that adds support for Docusaurus 3.5.0+. As mentioned before, this change requires breaking backward compatibility.

[anovis]

nice! thanks for the fix. any timeline for when you think you will push this release to npm?

[robbieaverill]

I just tested the latest canary release 0.0.0-763 and things build correctly.

[robbieaverill]

Stable release v4.0.0 contains the fix for this

[pcolby]

Stable release v4.0.0 contains the fix for this

Confirmed working for me now (with Docusaurus v3.5.2). Thanks!

[IanVS]

@sserrata I attempted to upgrade to docusaurus 3.5.2 and version 4.0.1 of this plugin, and got errors. I found that some 3.4.0 docusaurus packages are still installed, I believe due to the range on

docusaurus-openapi-docs/packages/docusaurus-theme-openapi-docs/package.json

Line 39 in e228de9

"@docusaurus/theme-common": "^3.0.1",

. This should be ^3.5.0, to ensure that an older, incompatible version of @docusaurus/theme-common is not used. I'll open a PR shortly.