Docusaurus V4 - Umbrella issue

[slorber]

This is a meta issue to gather information about the upcoming Docusaurus v4 release.
This comment will be updated regularly as we progress toward v4.

If you have opinions on breaking changes and dependency upgrades we should focus on, please let us know.

Apart from that, I'd like to keep the release relatively small, to make it easy to adopt, and to not delay it more than needed.

Top Priority changes

These are the changes we really want for v4. The list is already quite long, so I'm likely to migrate some items to optional changes.

Dependency upgrades:

• Node 24+ (break: update all packages to Node 24.14 update node engine in packages #11914)
• React 19.2+ (break: upgrade to React 19.2+ #11916)
• TypeScript 6.0+ (break: require TypeScript >= 6.0 #11915)
• Rspack v2.0+
• DocSearch v4.6+ (break(search): upgrade Algolia DocSearch packages, require DocSearch 4.6+, drop v3 support #11917)
• React Router v8+ / history v5+
• Webpack/PostCSS/CSSNano/Bundler dependencies (break: upgrade webpack/bundler related dependencies #11924)
• react-helmet-async v3+ (v3.0.0 — React 19 support, TypeScript cleanup, switch to pnpm staylor/react-helmet-async#260)
• Cheerio v1.2+ (chore: upgrade cheerio #11922)
• jiti v2+ (feat(core): upgrade Jiti to v2 #12045) (or load config files with native Node.js TS support? later?)
• Babel 8?
• Replace Globby by Tinyglobby (chore: switch to tinyglobby #11042)
• Replace gray-matter by 11ty/gray-matter maintained fork (chore(deps): upgrade to @11ty/gray-matter v2 #12182)
• Feed v5 (PR)

Behaviors:

• Trusted publishing for official releases
• v4 future flags are turned on by default; we may provide an opt-out for some, like CSS Cascade Layers
• experimental_faster is now stable and enabled by default. It remains possible to opt out webpack/slower tools.
• experimental_storage is now stable and uses namespacing by default, with the ability to out-out.
• Remove deprecated APIs
• Use browserslist query baseline widely available by default
• Use native RegExp.escape
• Remove CLI built-in --bundle-analyzer option, it shouldn't be in core and could be a plugin
• Enable respectPrefersColorScheme by default
• Remove Google Analytics plugin
• Get rid of prop-types from client bundle
• Migrate docs/blog/pages-specific code from theme-common to plugin client exports
• TypeScript strict by default (cleanup init template, now useless since TS 6.0)
• Deprecate configureWebpack(...args) in favor of configureBundler({params}), upgrade webpack-merge

Also: handle all the // TODO Docusaurus v4 comments in code

Optional changes

These are the changes we'd like to have for v4, but if they are too complicated, difficult to implement, or too disruptive for users, we may postpone them to another major version.

• Deprecate algolia.themeConfig in favor of plugin/preset options?
• v4.0 milestone contains various fixes/upgrades requiring breaking changes or version upgrades
• Eta v4
• MathJax v4
• replace chalk by native APIs
• Babel 8 for Docusaurus Slower?
• Replace gray-matter by someething better?
• Deprecate getSwizzleComponentList in favor of getSwizzleConfig
• Truncate blog markdown loader with AST/remark instead of String split regexp
• .md parsed as CommonMark by default?
• Internalize and shrink down Infima
• Chokidar v4?
• Commander v12?
• Internalize Infima

[omonk]

Curious on the gray-matter replacement, what is the motivation there? No opinions on removing or replacing it, just curious!

Something I know that has been touted a lot is tailwind support. I've managed to get it running in my project but it doesn't feel that great. Infima seems to have lost development effort, commits from the last few years are dependabot PRs or minor improvements. Even the home page says it is being developed alongside v2 of docusaurus so it feels quite stale. Moving it into docusaurus feels like a good step and would remove confusion and give developers a clearer path to customisation.

[slorber]

gray-matter is mostly unmaintained and also has some weird behaviors, like a confusing internal front matter caching system that makes it unsafe to modify the object it returns. I'm pretty sure I've seen newer front matter libraries that are maintained, faster, and safer to use.

Infima is not developed outside of Docusaurus. I'd like to re-integrate it into Docusaurus theme classic to reduce maintenance friction (added it to the list). That would actually help us port our theme to Tailwind.

[eMUQI]

.md parsed as CommonMark by default?

Hi, will there be an option to configure how .md files are parsed? Currently .md files are parsed as MDX, and my editor has excellent syntax highlighting and formatting support for Markdown files but no support for MDX files, so I exclusively use .md files (I haven't found a suitable MDX VS Code extension yet). What's the end goal of this parsing behavior change? Will parsing options be available, or will they eventually be phased out until only CommonMark parsing remains? This is important for my future documentation work. Thanks!

[danielclow]

Would love to see Infima merged into Docusaurus in v4. This would definitely reduce confusion and make it easier for users to customize things.

[slorber]

Hi, will there be an option to configure how .md files are parsed? Currently .md files are parsed as MDX, and my editor has excellent syntax highlighting and formatting support for Markdown files but no support for MDX files, so I exclusively use .md files (I haven't found a suitable MDX VS Code extension yet). What's the end goal of this parsing behavior change? Will parsing options be available, or will they eventually be phased out until only CommonMark parsing remains? This is important for my future documentation work. Thanks!

We already have options to parse md as CommonMark, it's just not have full feature parity with MDX. Note, in both cases, things are parsed with MDX, which has a format: 'md' mode.

https://docusaurus.io/docs/markdown-features#mdx-vs-commonmark

We'd like to keep supporting both modes and ensure both have feature parity. For example, in format: md mode it's not possible to use Tabs currently because our API relies on JSX. In the future, we could bring this feature parity for tabs by exposing an html-like syntax (<tabs> instead of <Tabs>) or a directive syntax (:::tabs). Hope this makes sense.

[StefanWallin]

The ajv ReDoS-vuln that popped up yesterday made me notice that @docusaurus/bundler depend on the deprecated and archived https://github.com/webpack-contrib/file-loader. Is moving to RSPack removing this slightly problematic old dependency chain?

❯ pnpm why ajv
ajv@6.12.6
├─┬ ajv-keywords@3.5.2
│ └─┬ schema-utils@3.3.0
│   ├─┬ file-loader@6.2.0
│   │ ├─┬ @docusaurus/bundler@3.9.2
|   | | ...
│   │ ├─┬ @docusaurus/mdx-loader@3.9.2
|   | | ...
│   │ ├─┬ @docusaurus/utils@3.9.2
|   | | ...
│   │ └─┬ url-loader@4.1.1
|   |   ...
│   ├─┬ null-loader@4.0.1
│   │ └── @docusaurus/bundler@3.9.2 [deduped]
│   └── url-loader@4.1.1 [deduped]
└── schema-utils@3.3.0 [deduped]

[rainecheck]

One of the items on the v4 milestone is eslint v9 compatibility for the docusaurus eslint plugin. eslint v10 has since been released, so this might need to be re-looked at.

[sanjaiyan-dev]

Hello 👋

I was wondering if we could consider adding React Compiler support for v4? The React team actually suggests compiling libraries, as mentioned in their documentation.

My initial thought is to update the docusaurus-babel preset (around here) to include the compiler plugin. For a safe migration, we could optionally enable it using compilationMode: 'annotation'.

Please let me know if this makes sense. I apologize if this isn't the right approach or place for this, but I would be more than happy to submit a PR if you're open to the idea!

Thank you!

[slorber]

TLDR: not the right time to accept React Compiler PRs.

However, our codebase already respects the React Compiler eslint rules: #10969

---

It doesn't seem like the right timing to work on a React Compiler integration, considering it only integrates nicely with Babel, and we want to enable Docusaurus Faster (Rspack/SWC) by default for v4. Although technically possible (see what Next.js is doing), it's challenging and probably better to wait.

The React team is porting the React Compiler to Rust, which would make it possible to integrate with SWC in a better, more performant way in the future: oxc-project/oxc#10048

Note that if your site uses Babel (not opting in for Docusaurus Faster) and want to use the React Compiler, you can already add the plugin to your site's Babel config, and it should normally work. However, this will only optimize your site's source code, which is generally composed of MDX more than JSX/TSX, so there's probably not much to optimize there.

IMHO, most of the code to optimize is in the official theme packages. We plan to optimize that code later, too, once SWC can support the React Compiler. But there's something to consider: docusaurus swizzle can eject theme files to your site's source, and the emitted code must remain readable, easy to edit manually. So, even if we pre-compile our lib, we still want our "source" to be sufficiently optimized so that if a site ejects it and is not using the compiler, that code remains fast. We don't want "ejecting" to make your site slower.

[sanjaiyan-dev]

TLDR: not the right time to accept React Compiler PRs.

However, our codebase already respects the React Compiler eslint rules: #10969

It doesn't seem like the right timing to work on a React Compiler integration, considering it only integrates nicely with Babel, and we want to enable Docusaurus Faster (Rspack/SWC) by default for v4. Although technically possible (see what Next.js is doing), it's challenging and probably better to wait.

The React team is porting the React Compiler to Rust, which would make it possible to integrate with SWC in a better, more performant way in the future: oxc-project/oxc#10048

Note that if your site uses Babel (not opting in for Docusaurus Faster) and want to use the React Compiler, you can already add the plugin to your site's Babel config, and it should normally work. However, this will only optimize your site's source code, which is generally composed of MDX more than JSX/TSX, so there's probably not much to optimize there.

IMHO, most of the code to optimize is in the official theme packages. We plan to optimize that code later, too, once SWC can support the React Compiler. But there's something to consider: docusaurus swizzle can eject theme files to your site's source, and the emitted code must remain readable, easy to edit manually. So, even if we pre-compile our lib, we still want our "source" to be sufficiently optimized so that if a site ejects it and is not using the compiler, that code remains fast. We don't want "ejecting" to make your site slower.

Thanks for the explanation, that makes sense.

Would you be open to me taking a stab at a React Router v7 migration? I'd like to "just try" and see what the feasibility looks like, but I wanted to check if you'd be interested in that before I start tinkering with it.

[slorber]

Would you be open to me taking a stab at a React Router v7 migration? I'd like to "just try" and see what the feasibility looks like, but I wanted to check if you'd be interested in that before I start tinkering with it.

Thanks for the proposal, but I'd rather not. This is one of the things that is the most likely to produce subtle but annoying breaking changes to our community and is the first thing I plan to work on for Docusaurus v4. I'm also directly in touch with the React Router team and we'll likely upgrade to React Router v8. We already had a POC of upgrading to v6 here: #6037