Upgrade Docusaurus to v3.7

[taraspos]

Summary

Upgrade Docusaurus to 3.7:

• Add @docusaurus/plugin-svgr to fix SVG build issues (Thanks @emargetis)
• Override @rspack/core to v1.2.5 to fix build issues (Thanks @slorber):
  • [Bug]: width 3 given for non-narrow character error when building certain libraries web-infra-dev/rspack#9075
  • [Bug]Panic in non-narrow character when generate source map swc-project/swc#10010

Testing

Preview looks good:

• https://taras-docusaurus-upgrade.d2mrezcly5gcqm.amplifyapp.com/docs/

[taraspos]

Currently the build is failing with:

% RUST_BACKTRACE=1 RUST_BACKTRACE=full yarn build
...
● Client ██████████████████████████████████████████████████ (28%) building json|/workspaces/docs-website/.docusaurus/docusaurus-plugin-content-docs/default/site-versioned-docs-version-16-x-enroll-resources-application-acces
● Server ██████████████████████████████████████████████████ (31%) building json|/workspaces/docs-website/.docusaurus/docusaurus-plugin-content-docs/default/site-versioned-docs-version-16-x-enroll-resources-database-access-e
Panic occurred at runtime. Please file an issue on GitHub with the backtrace below: https://github.com/web-infra-dev/rspack/issues
Message:  width 3 given for non-narrow character
Location: index.crates.io-6f17d22bba15001f/swc_common-5.0.0/src/syntax_pos.rs:714

Run with COLORBT_SHOW_HIDDEN=1 environment variable to disable frame filtering.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ BACKTRACE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
<empty backtrace>
Aborted
error Command failed with exit code 134.

[github-actions]

Amplify deployment status

Branch	Commit	Job ID	Status	Preview	Updated (UTC)
taras/docusaurus-upgrade	9411551	13	✅SUCCEED	taras-docusaurus-upgrade	2025-03-07 18:51:19

[taraspos]

This is probably related to:

• When using @docusaurus/faster, if there is some Chinese in the md file when packaging on version 3.6, an error message will be displayed, such as byte index 4 is not a char boundary. facebook/docusaurus#10646

[taraspos]

Building with COLORBT_SHOW_HIDDEN=1 SKIP_HTML_MINIFICATION=true RUST_BACKTRACE=1 RUST_BACKTRACE=full NODE_ENV=production yarn build don't seem to help

[slorber]

@taraspos answering your comment here: facebook/docusaurus#10556 (comment)

If it works with rspackBundler: false but doesn't with rspackBundler: true, then it's very likely a Rspack bug that you should report to the Rspack team directly (or maybe SWC, not sure).

cc @hardfist

---

It can be reproduced using latest Docusaurus canary using @rspack/core@1.2.2 that recently upgraded to SWC core to v10: https://rspack.dev/blog/announcing-1-2#upgrade-swc-plugins

When disabling Docusaurus Faster options related to SWC, it still reproduces:

const config: Config = {
  future: {
    v4: true,
    experimental_faster: {
      swcJsLoader: false,
      swcJsMinimizer: false,
      swcHtmlMinimizer: false,
      lightningCssMinimizer: true,
      rspackBundler: true,
      mdxCrossCompilerCache: true,
      ssgWorkerThreads: true,
    },
  },
}

However, when disabling Rspack (using Webpack), it doesn't crash anymore.
(in this case it's not using the built-in Rspack SWC support so it's not 100% the same SWC)

const config: Config = {
  future: {
    v4: true,
    experimental_faster: {
      swcJsLoader: true,
      swcJsMinimizer: true,
      swcHtmlMinimizer: true,
      lightningCssMinimizer: true,
      rspackBundler: false,
      mdxCrossCompilerCache: true,
      ssgWorkerThreads: true,
    },
  },
}

However, we still get various errors:

 

[ERROR] Client bundle compiled with errors therefore further build is impossible.
Module not found: Error: Can't resolve '../../../data/events.json' in '/Users/sebastienlorber/Desktop/docs-website/src/components/Header'

--------------------------

Module not found: Error: Can't resolve '../../../data/navbar.json' in '/Users/sebastienlorber/Desktop/docs-website/src/components/Header'

--------------------------

Module parse failed: Identifier 'codeBlockStyles' has already been declared (10:7)
File was processed with these loaders:
 * ./node_modules/swc-loader/src/index.js
You may need an additional loader to handle the result of these loaders.
| import codeBlockStyles from "./CodeBlock.module.css";
| import commandStyles from "/src/components/Command/Command.module.css";
> import codeBlockStyles from "./CodeBlock.module.css";
| const TIMEOUT = 1000;
| const Pre = (param)=>{

--------------------------

Cannot read properties of null (reading 'getExportsType')
while analyzing module /Users/sebastienlorber/Desktop/docs-website/node_modules/swc-loader/src/index.js??ruleSet[1].rules[5].use[0]!/Users/sebastienlorber/Desktop/docs-website/src/components/Header/Header.tsx for concatenation

--------------------------

assets/css/styles.c9838b2e.css from Css Minimizer plugin
SyntaxError: Unexpected token Ident("-fs-text-sm")

--------------------------

assets/css/styles.412b9614.css from Css Minimizer plugin
SyntaxError: Unexpected token Ident("-fs-text-sm")

Your repro is not really usable as is since the data folder doesn't contain the Sanity files, requiring env variables to be set.

However, fixing the errors above does not fix the Rspack/SWC crash.

Reverting to Rspack 1.1 fixes the bundling crash:

  "resolutions": {
    "@rspack/core": "1.1.8"
  },

[taraspos]

@slorber, thanks for such a detailed response!

[slorber]

The bug has been fixed in our deps, I guess it should work soon on our next release

• [Bug]: width 3 given for non-narrow character error when building certain libraries web-infra-dev/rspack#9075
• [Bug]Panic in non-narrow character when generate source map swc-project/swc#10010

[taraspos]

Thanks @slorber !

[slorber]

np 👍

Try Rspack 1.2.3, this might fix the problem (not sure):
https://github.com/web-infra-dev/rspack/releases/tag/v1.2.3

[slorber]

The Rust panic error should be fixed in https://github.com/web-infra-dev/rspack/releases/tag/v1.2.5 (included in SWC 14 upgrade)

[emargetis]

After upgrading to Docusaurus 3.7 we were experiencing some build issues with SVGs:

It turns out that in Docusaurus 3.7 SVG support was extracted so we needed to add the package to our dependencies and add it to the plugins section of docusaurus.config.ts (since we don't use their presets)