Bump docusaurus to v3.9 latest #945
Conversation
github-actions
bot
requested review from
akashraj4261,
dariavladykina and
jillian-maroket
martindekov
force-pushed
the
bump-9791
branch
from
3e2b6f6 to
d2e81b3
Compare
There was a problem hiding this comment.
Pull request overview
This PR upgrades Docusaurus from v2.4.0 to v3.9.0 and updates related dependencies to maintain compatibility with the major version bump.
Key Changes:
- Docusaurus core and plugins upgraded from v2.4.0 to v3.9.0
- Supporting packages updated: @mdx-js/react (v1.6.22 → v3.0.0), prism-react-renderer (v1.3.1 → v2.4.0), and OpenAPI documentation plugins (v2.1.2 → v4.5.1)
- Updated theme imports in docusaurus.config.js to use the new prism-react-renderer v2 API structure
Reviewed changes
Copilot reviewed 4 out of 5 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| package.json | Updates all Docusaurus dependencies from v2.4.0 to v3.9.0, along with related plugin and renderer upgrades |
| docusaurus.config.js | Refactors prism-react-renderer theme imports to use the new v2 API structure with destructured themes |
| sidebars.js | Attempts to change sidebar import from .js to .ts and adds ES module compatibility handling |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
martindekov
force-pushed
the
bump-9791
branch
2 times, most recently
from
5b1d290 to
90b9773
Compare
martindekov
force-pushed
the
bump-9791
branch
4 times, most recently
from
5d099ae to
0016c13
Compare
martindekov
force-pushed
the
bump-9791
branch
4 times, most recently
from
1fe4fcc to
771795d
Compare
martindekov
changed the title
martindekov
left a comment
martindekov
left a comment
There was a problem hiding this comment.
PR Tests Fail because the pipeline is using the target branch where nodejs is still 18, while docosaurus 3. requires nodejs at least 20 which is introduced in this PR
There was a problem hiding this comment.
Hi,
@olblak asked me to review this PR.
I took a fresh copy of the repo and followed the steps as described in README.md. All worked well and yarn start showed me a generated website that looks as expected.
Tested on node 20.19.6 (latest available 20) and Docusaurus 3.9.2.
The README.md still refers to Docusaurus 2, so that could be included in this PR too.
The README.md also refers to the step for generating PDF docs yarn gen-pdf-docs. I don't know if this is in current use. It trundles through docs located at the testing localhost but eventually fails when trying to use the API docs at http://localhost:3000/v1.7/api/list-namespaced-persistent-volume-claim.
[08.01.2026 12:51.56.175] [LOG] Retrieving html from http://localhost:3000/v1.7/api/list-namespaced-persistent-volume-claim
[08.01.2026 12:51.58.690] [DEBUG] Found 12 elements
[08.01.2026 12:51.58.696] [DEBUG] Clicking summary: Path Parameters
[08.01.2026 12:51.59.534] [DEBUG] Clicking summary: Query Parameters
[08.01.2026 12:52.00.370] [DEBUG] Clicking summary: Schema
[08.01.2026 12:52.01.199] [DEBUG] Clicking summary: metadata object
[08.01.2026 12:52.02.026] [DEBUG] Clicking summary: Schema
[08.01.2026 12:52.02.047] [ERROR] Error: Node is either not clickable or not an Element
at CdpElementHandle.clickablePoint (/home/jhk/projects/suse/community/harvester/harvester-community-docs/node_modules/puppeteer-core/lib/cjs/puppeteer/api/ElementHandle.js:673:23)
at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
at async CdpElementHandle.<anonymous> (/home/jhk/projects/suse/community/harvester/harvester-community-docs/node_modules/puppeteer-core/lib/cjs/puppeteer/api/ElementHandle.js:250:32)
at async CdpElementHandle.click (/home/jhk/projects/suse/community/harvester/harvester-community-docs/node_modules/puppeteer-core/lib/cjs/puppeteer/api/ElementHandle.js:703:30)
at async CdpElementHandle.<anonymous> (/home/jhk/projects/suse/community/harvester/harvester-community-docs/node_modules/puppeteer-core/lib/cjs/puppeteer/api/ElementHandle.js:253:36)
at async openDetails (/home/jhk/projects/suse/community/harvester/harvester-community-docs/node_modules/docs-to-pdf/lib/utils.js:212:13)
at async generatePDF (/home/jhk/projects/suse/community/harvester/harvester-community-docs/node_modules/docs-to-pdf/lib/utils.js:82:21)
error Command failed with exit code 1.
Also, I think the GH actions might need updating to use node 20.
Thanks.
|
Thanks for going through this @jhkrug:
It's interesting why it fails on localhost, this is accessible when built by pipeline - https://695d36cc2dd041bc91b0f6b1--harvester-preview.netlify.app/v1.7/api/list-namespaced-persistent-volume-claim/ but I will double check on localhost as well. All good catches really appreciate the input! |
|
ok so this fails on main as well 🤔 will add the owners in the loop @jillian-maroket @akashraj4261 @dariavladykina do you folks have any idea why |
martindekov
requested review from
akashraj4261,
dariavladykina and
jillian-maroket
It was |
|
Yes, sorry @jhkrug I copied the wrong key, the output is from |
|
So @jhkrug for your original review:
Fixed to point docosaurus 3 and references to 3.9 release introduced in this PR ✔️
We don't use this and we never did and it fails on main that's the reason no one said anything so removed the explanation altogether from the README ✔️
Actually did update to node 20 in this PR in folder - .github/workflows but since pipeline is using config from main it fails with node version 18 as main still has not adopted this change which bumps it so pipeline cannot use it, I fixed this in testing PR where pipeline is using node version 20. |
jhkrug
left a comment
jhkrug
left a comment
There was a problem hiding this comment.
lgtm. I can only comment, not approve.
|
Thanks for the input and review @jhkrug appreciate it! |
|
Thank you very much @jhkrug for your help |
| webpack: { | ||
| jsLoader: (isServer) => ({ | ||
| loader: require.resolve("swc-loader"), |
There was a problem hiding this comment.
Is it possible that we switch to swc-loader? 50 minutes build time is too long.
There was a problem hiding this comment.
Thanks for the input Jack, this (slower build time) was concerning for me as well, but official docs suggests this. I will try to return configuration of this in combination of experimental feature faster as simply reverting won't work. Compilation breaks so this faster feature need to be fine tuned. Will go over the code in the docosaurus 3.9 and try out some configs and let you know if it works.
There was a problem hiding this comment.
So with the following config:
webpack: {
jsLoader: (isServer) => ({
loader: require.resolve("swc-loader"),
options: {
jsc: {
parser: {
syntax: "typescript",
tsx: true,
},
target: "es2019",
transform: {
react: {
runtime: "automatic",
},
},
},
module: {
type: isServer ? "commonjs" : "es6",
},
},
}),
},
future: {
v4: true,
experimental_faster: {
swcJsLoader: false, // using custom webpack.jsLoader above
swcJsMinimizer: true, // use js minimzer
swcHtmlMinimizer: true, // use html minimzer
lightningCssMinimizer: true, // use css minimizer
mdxCrossCompilerCache: true, // use cache
rspackBundler: false, // Stay with Webpack (Rspack has perf issues)
},
},
I reduced build time to 38 minutes:
mdekov@localhost:~/go/src/github.com/harvester/docs> yarn start
yarn run v1.22.22
$ NODE_OPTIONS='--max-old-space-size=7168' docusaurus start
[INFO] Starting the development server...
[SUCCESS] Docusaurus website is running at: http://localhost:3000/
✔ Client
Compiled successfully in 38.38m
client (webpack 5.104.1) compiled successfully
So basically between rspack and webpack, webpack is still better but not as fast as the previous runs of ~15-20 minutes. Let me know if you think we can optimize this further. Also the original webpack config as is is not working with 2.4 so that's why it had to be slightly modified to include this new features field in the config.
I'd appreciate if you know someone who can suggest even further optimizations, in my previous tests this was the closes I could get to with webpack.
There was a problem hiding this comment.
And with the current change as is the build takes around 2150 seconds which is around 35 minutes timed through script, so its more or less the same when building locally webpack vs simply enabling the faster feature and with the pipeline preparation probably it will stilltake ~50-60 minutes for both approaches
There was a problem hiding this comment.
@Yu-Jack based on the input above, do you think the slow build time is a deal breaker for adopting the newest docosaurus or we can merge this as is and open separate issue to optimize build times further?
There was a problem hiding this comment.
Or you can just apply the change to this PR after you find a good method (it would be better). Besides, I think 35 minutes is a good record for right now.
There was a problem hiding this comment.
I noticed this problem quite early and tried combination of a lot of configurations, the current configuration yielded the best result. In the beginning when I migrated to 3.9 builds took around 1 hour and 30 minutes (locally) so getting it down (again locally) to ~30-35 minutes was success in comparison. So there might be a hidden variable which I missed or certain combination of commands and configurations but best optimization I think is effort on it's own as this change already:
- fixes the build with 3.9
- fixes the pipeline
- migrates the incompatibilities
- optimizes best as per documentation suggestions
So I can open separate issue and paste it here before merging this change ?
There was a problem hiding this comment.
@Yu-Jack pipeline is green and this is ready to be merged, I can open a separate issue for this discussion and further optimization? If so can you approve this and we can proceed with merging
There was a problem hiding this comment.
With Docusaurus Faster, it's supposed to be faster and you don't need to apply a custom jsLoader: this way Rspack uses it's built-in Rust-based JS loader (no serialization between rust<->js when bundling)
If things are slow, it's worth reporting precisely which step of the build is slow here: facebook/docusaurus#11664 (comment)
There was a problem hiding this comment.
wow thanks for the input @slorber really appreciate it and I did not expect from you to go as far as to review this specific PR so thank you twice. I will run this and report you back
|
@martindekov Before you merge, please check the following PRs from @m-ildefons . From PR 545: |
Bumping docosaurus to v3.9 along with adding the following: * Replace webpack optimizations with experimental_faster package which works with 3.9 while the webpack is breaking the builds * Replace latest setup node action with new node version 20 required by docusaurus builds * Fix broken escape characters, backslashes `\` break the build and are replaced with single quotes * Fix broken imports * Fix broken configuration and paths Signed-off-by: Martin Dekov <martin.dekov@suse.com>
Updating README file by pointing that we use Docosaurus 3 as opposed to 2 and point to the exact major.minor version to the docs. Remove suggestion for generating PDF docs as no one is using it and it does not work in main. So explaining the usage is redundant in that case. Signed-off-by: Martin Dekov <martin.dekov@suse.com>
martindekov
force-pushed
the
bump-9791
branch
from
5d1ad6c to
c28cf34
Compare
|
thanks for the references @jillian-maroket I think 3.9 is compatible with openapi generation through the: |
|
|
Pipeline is green, his is ready to merge |
Yu-Jack
left a comment
Yu-Jack
left a comment
There was a problem hiding this comment.
Thanks. It would be better to have the optimization method as soon as possible.
Yu-Jack
left a comment
Yu-Jack
left a comment
There was a problem hiding this comment.
Hold on. We might have to discuss about this in Slack with other people. They have some thoughts about this.
|
Hi @martindekov, |
|
Hey @Vicente-Cheng I attempted to do what @Yu-Jack did back in 2.4 in: #602 and see what docosaurus doc site configured for their site. Copying their approach yielded ~30 minute build time again. So it seems like what Jack did back then was exception for that version, but not the rule as he optimized the build on 2.4 from ~30 minutes to ~7-8 minutes again. For that I compiled all my optimization approaches and opened discussion in the Docosaurus community for insight to know if such build times are even possible on 3.X: |
7 participants
Bumping docosaurus to v3.9 along with adding the following:
which works with 3.9 while the webpack is breaking the builds
by docusaurus builds
\break the buildand are replaced with single quotes
Problem:
Docusaurus currently is older 2.4 version almost 2 years old now: harvester/harvester#9791
Solution:
Bump version to latest 3.9 - https://docusaurus.io/blog/releases/3.9
Related Issue(s):
harvester/harvester#9791
Test plan:
Pipeline test: #949
Site URL running on 3.9: https://695d36cc2dd041bc91b0f6b1--harvester-preview.netlify.app/
Start with clear up
yarn install
yarn gen-api-docs
yarn start (this takes ~40 minutes)
Additional documentation or context
Docusaurus 3.9 Doc - https://docusaurus.io/blog/releases/3.9
Faster feature replacing webpack: