Ir para o conteúdo principal
Sébastien Lorber
Docusaurus maintainer, This Week In React editor

A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.

View all authors

Docusaurus 3.8

· Leitura de 11 minutos
Sébastien Lorber
Docusaurus maintainer, This Week In React editor

We are happy to announce Docusaurus 3.8.

This release improves build performance, includes new features and introduces "Future Flags" to prepare your site for Docusaurus 4.

Upgrading is easy. We follow Semantic Versioning, and minor version updates have no breaking changes, accordingly to our release process.

Docusaurus blog post social card

Performance

This release keeps improving our build infrastructure performance with various optimizations, and 2 new Docusaurus Faster options.

Docusaurus Faster

Docusaurus Faster has been introduced in Docusaurus v3.6, and permits you to opt-in for our upgraded build infrastructure and helps you build your site much faster. The experimental flags can be turned on individually, but we recommend to turn them all at once with this convenient shortcut:

const config = {
future: {
experimental_faster: true,
},
};
tip

Don't forget to install the @docusaurus/faster dependency first!

Persistent Cache

In #10931, we have enabled the Rspack persistent cache. Similarly to the Webpack persistent cache (already supported), it permits to greatly speed up the bundling of the Docusaurus app on subsequent builds.

In practice, your site should build much faster if you run docusaurus build a second time.

This feature depends on using the Rspack bundler, and can be turned on with the rspackPersistentCache flag:

const config = {
future: {
experimental_faster: {
rspackBundler: true, // required flag
rspackPersistentCache: true, // new flag
},
},
};
Preserving the cache

The persistent cache requires preserving the ./node_modules/.cache folder across builds.

Popular CDNs such as Netlify and Vercel do that for you automatically. Depending on your CI and deployment pipeline, additional configuration can be needed to preserve the cache.

Result: On average, you can expect your site's bundling time to be ~2-5× faster on rebuilds 🔥. The impact can be even more significant if you disable the optional concatenateModule optimization.

Worker Threads

In #10826, we introduced a Node.js Worker Thread pool to run the static side generation code. With this new strategy, we can better leverage all the available CPUs, reduce static site generation time, and contain potential memory leaks.

This feature can be turned on with the ssgWorkerThreads flag, and requires the v4.removeLegacyPostBuildHeadAttribute Future Flag to be turned on:

const config = {
future: {
v4: {
removeLegacyPostBuildHeadAttribute: true, // required
},
experimental_faster: {
ssgWorkerThreads: true,
},
},
};

Result: On average, you can expect your site's static site generation time to be ~2× times faster 🔥. This was measured on a MacBook Pro M3 and result may vary depending on your CI.

Other Optimizations

We identified and resolved several major bottlenecks, including:

  • In #11007, we optimized the dev server startup time for macOS users. We figured out that the code to open your browser used expensive synchronous/blocking calls that prevented the bundler from doing its work. From now on, the bundler and the macOS browser opening will run in parallel, leading to a faster docusaurus start experience for all macOS users.
  • In #11163, we noticed that the docs showLastUpdateAuthor and showLastUpdateTime are quite expensive, and require to run a git log command for each document. On large sites, running these commands in parallel can exhaust the system and lead to Node.js EBADF errors. We implemented a Git command queue to avoid exhausting the system, which also slightly increased performance of our plugin's loadContent() lifecycle.
  • In #10885, we implemented an SVG sprite for the external link icon. Due to its repeated appearance in various places of your site (navbar, footer, sidebars...), using a React SVG component lead to duplicated SVG markup in the final HTML. Using a sprite permits to only embed the icon SVG once, reducing the generated HTML size and the static generation time. We plan to use more SVG sprites in the future.
  • In #11176, we fine-tuned the webpack/Rspack configuration to remove useless optimizations.
tip

If bundling time is a concern, consider disabling the optional concatenateModule bundler optimization. We explain the tradeoffs and how to do it here. It only saves 3% JS, and for a very large site, this change was incredibly impactful: 4x faster on cold builds, x16 faster rebuilds 🔥.

Impact

We have upgraded the React Native website to Docusaurus v3.8 already. Here's an updated benchmark showing the global Docusaurus Faster impact on total build time for a site with ~2000 pages:

ReactNative.devCold BuildWarm Rebuild
🐢 Docusaurus Slower120s (baseline)33s (3.6 × faster)
⚡️ Docusaurus Faster31s (3.8 × faster)17s (7 × faster)

We measured similar results on our website:

Docusaurus.ioCold BuildWarm Rebuild
🐢️ Docusaurus Slower146s (baseline)45s (3.2 × faster)
⚡️ Docusaurus Faster42s (3.5 × faster)24s (6.1 × faster)

You can also expect memory usage improvements, and a faster docusaurus start experience.

Future Flags

The Docusaurus v4 Future Flags let you opt-in for upcoming Docusaurus v4 breaking changes, and help you manage them incrementally, one at a time. Enabling all the future flags will make your site easier to upgrade to Docusaurus v4 when it's released.

not invented here

The concept of Future Flags is not our invention. It has been popularized in the Remix community. You can read more about this gradual feature adoption strategy here:

Turn all the v4 future flags on

You can turn all the v4 Future Flags on at once with the following shortcut:

const config = {
future: {
v4: true,
},
};

This way, you are sure to always keep your site prepared for Docusaurus v4. Be aware that we'll introduce more Future Flags in the next minor versions. When upgrading, always read our release blog posts to understand the new breaking changes you opt into.

CSS Cascade Layers

In Docusaurus v4, we plan to leverage CSS Cascade Layers. This modern CSS feature is widely supported and permits to group CSS rules in layers of specificity. It is particularly useful to give you more control over the CSS cascade. It makes the CSS rules less dependent on their insertion order. Your un-layered rules will now always override the layered CSS we provide.

In #11142, we implemented a new experimental @docusaurus/plugin-css-cascade-layers that you can turn on through the v4.useCssCascadeLayers flag if you use the classic preset:

export default {
future: {
v4: {
useCssCascadeLayers: true,
},
},
};

We consider this feature as a breaking change because it can slightly alter the CSS rules application order in customized sites. These issues are usually limited, and relatively easy to fix (see for example the React Native CSS changes). Sites that do not provide custom CSS and do not swizzle any component should not be affected.

In practice, it permits to automatically apply built-in CSS Cascade Layers to all the CSS we provide, including our opinionated CSS framework Infima:

@layer docusaurus.infima {
h1 {
/* Infima css rules */
}
pre {
/* Infima css rules */
}
}

Layers can help solves our long-standing Global CSS pollution issue. Our built-in global CSS rules may conflict with yours, making it harder to use Docusaurus to create playgrounds, demos and embedded widgets that are isolated from our CSS. Thankfully, CSS Cascade Layers can be reverted to create HTML subtrees that are not affected by the CSS Docusaurus provides.

Reverting layers

As this issue and this blog post explain, it is possible to revert layers to isolate an HTML subtree from the CSS that comes from that layer.

In practice, you can create a .my-playground class to revert the global CSS coming from Infima:

/* The "impossible" :not() selector helps increase the specificity */
.my-playground:not(#a#b) {
&,
* {
@layer docusaurus.infima {
all: revert-layer;
}
}
}

Then you can apply this class to any HTML element, so that Infima doesn't apply to any of its children. The HTML subtree becomes isolated from our built-in CSS.

/tests/pages/style-isolation?docusaurus-data-navbar=false

postBuild() Change

In #10850, we added a new removeLegacyPostBuildHeadAttribute Future Flag that slightly changes the signature of the postBuild() plugin lifecycle method, removing the head attribute.

export default {
future: {
v4: {
removeLegacyPostBuildHeadAttribute: true,
},
},
};

This legacy data structure is coming from our react-helmet-async dependency and should have never been exposed as public API in the first place. It is not serializable, which prevents us from implementing Worker Threads for the static site generation.

While technically a breaking change, we believe this change will not affect anyone. We couldn't find any open source plugin that uses the head parameter that this method receives. If turning this flag on breaks your site, please let us know here.

System Color Mode

In #10987, the classic theme now lets you revert the color mode to the system/OS value.

http://localhost:3000

Code Block Refactor

In #11058, #11059, #11062 and #11077, the theme code block components have been significantly refactored in a way that should be much easier to swizzle and extend.

According to our release process, this is not a breaking change, but sites that have swizzled these components may need to upgrade them.

Translations

  • 🇹🇷 #10893: Add missing Turkish theme translations.
  • 🇵🇱 #10884: Add missing Polish theme translations.
  • 🇨🇳 #10816: Add missing Chinese theme translations.
  • 🇯🇵 #11030: Add missing Japanese theme translations.

Maintenance

Docusaurus 3.8 is ready for Node.js 24 and TypeScript 5.8.

We also removed useless npm packages and internalizing unmaintained ones:

  • In #11010 and #11014, we internalized the unmaintained react-ideal-image and react-waypoint package used in @docusaurus/plugin-ideal-image, and made them compatible with React 19.
  • In #10956, we removed our dependency to the unmaintained react-dev-utils package (from Create-React-App).
  • In #10358, we replaced the unmaintained shelljs package by execa
  • In #11138, we removed the reading-time package in favor of the built-in Intl.Segmenter standard API to compute blog post reading times.
  • In #11037, we removed the useless clean-webpack-plugin.

Other changes

Other notable changes include:

  • In #10852, the theme docsVersionDropdown navbar item now accepts a versions attribute.
  • In #10953, the @docusaurus/remark-plugin-npm2yarn plugin now supports Bun tabs conversions by default.
  • In #10945, more stable CSS classes are now applied to the main theme layout elements, to let you create more reliable CSS selectors.
  • In #10846, the Markdown code block showLineNumbers metastring can now accept a number to initialize the line counter initial value.
  • In #11090, we made it easier to provide a custom page title formatter.
  • In #11088, the page plugin now supports frontMatter.slug like docs and blog plugins already do.
  • In #10875, the docs versioning CLI now also copies localized docs JSON translation files.

Check the 3.8.0 changelog entry for an exhaustive list of changes.

Docusaurus 3.7

· Leitura de 3 minutos
Sébastien Lorber
Docusaurus maintainer, This Week In React editor

We are happy to announce Docusaurus 3.7.

Docusaurus is now compatible with React 19.

Upgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.

Docusaurus blog post social card

Highlight

React 19

In #10763, we added support for React 19, and the Docusaurus website is running on React 19 already.

From now on, all newly initialized sites will run on React 19 by default, and React 19 will be the minimum required version Docusaurus v4.

However, React 18 remains supported, and existing Docusaurus sites can either choose to stay on React 18, or upgrade their dependencies to React 19:

{
"name": "my-docusaurus-site",
"dependencies": {
- "react": "^18.0.0",
- "react-dom": "^18.0.0"
+ "react": "^19.0.0",
+ "react-dom": "^19.0.0"
}
}
warning

There's no urge to upgrade your site immediately.

React 19 is a bit heavier than React 18. Since we support both versions, we don't leverage yet the new features that are exclusive to React 19.

However, upgrading to React 19 prepares your site for Docusaurus v4, that will drop support for React 18.

Here are good reasons to upgrade your site before Docusaurus v4:

  • You have custom React code and want to ensure it is ready for React19
  • You plan to leverage the brand-new React 19 features in your own code
  • You use custom or third-party plugins and want to ensure their compatibility
  • You have a monorepo and want to align the React dependency to v19 for all packages

Along the way, we fixed all the remaining hydration errors reported by React 19, some of them produced by our aggressive HTML minifier settings.

SVGR plugin

Docusaurus has built-in support for SVGR, allowing you to seamlessly import and use SVG files as React components:

import DocusaurusSvg from './docusaurus.svg';

<DocusaurusSvg />;

This built-in support has been the source of various bug reports due to the inability to customize the SVGR Options, in particular the SVG Optimizer options.

In #10677, we extracted a new @docusaurus/plugin-svgr that you can now configure according to your needs. It is included by default in our classic preset:

export default {
presets: [
[
'classic',
{
svgr: {
svgrConfig: {
// Your SVGR options ...
svgoConfig: {
// Your SVGO options ...
// Use "svgoConfig: undefined" to use a svgo.config.js file
},
},
},
},
],
],
};

Other changes

Other notable changes include:

  • #10768: Blog authors have built-in icons for social platforms bluesky, mastodon, threads, twitch, youtube, instagram.
  • #10729: Blog now supports frontMatter.sidebar_label
  • #10803: @docusaurus/remark-plugin-npm2yarn now supports Bun conversions.
  • #10672: Upgrade Algolia DocSearch to algoliasearch v5.
  • #10800: Docusaurus Faster turns Rspack incremental mode on by default.
  • #10783: Improve Dutch theme translations.
  • #10760: Improve Korean theme translations.

Check the 3.7.0 changelog entry for an exhaustive list of changes.

Docusaurus 3.6

· Leitura de 8 minutos
Sébastien Lorber
Docusaurus maintainer, This Week In React editor

We are happy to announce Docusaurus 3.6.

Docusaurus is now ⚡️⚡️⚡️ much faster to build your site.

Upgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.

Docusaurus blog post social card

Highlights

This release has been mostly focused on build performance through the Docusaurus Faster project.

Docusaurus Faster

The Docusaurus Faster project's goal is to reduce the build times and memory consumption.

We have worked on multiple optimizations and modernized our infrastructure to use faster Rust-based tools, notably:

  • 🦀 Rspack: Fast Rust-based web bundler, almost drop-in replacement for webpack
  • 🦀 SWC: Speedy Web Compiler, Rust-based platform for the Web (HTML, CSS, JS)
  • 🦀 Lightning CSS: An extremely fast CSS parser, transformer, bundler, and minifier

Impacts

Adopting a new infrastructure can have various impacts. It's impossible to list them all exhaustively, so let's focus on the major ones.

To help you adopt it easily, we have been fairly conservative in terms of expected static site output and browser support.

Build Time

Benchmarks on community site show that you can expect your production site to build ⚡️2 to 4 times faster! 🔥:

How to benchmark

About rebuilds

Rspack doesn't support persistent caching yet, but it's on the roadmap and should be implemented soon. We think it's not a problem for the adoption of Rspack considering a cold Rspack build is usually as fast as a warm Webpack build using persistent caching.

Memory Consumption

You should also notice an improvement in memory consumption:

  • The new infrastructure consumes less memory overall
  • We fixed an important memory leak that affects in particular i18n sites
  • We added CI checks to ensure that we don't regress, and that our site and init template can both build in a memory-constrained environments
  • We added internal tooling to better understand which step of a build consumes memory
  • We removed a process.exit(0) that can hide memory leaks in your own code and third-party plugins

Other Impacts

Adoption Strategy

This new infrastructure is a breaking change, but it is opt-in and does not require a new major version of Docusaurus.

Before using Docusaurus Faster, add this new package:

npm install @docusaurus/faster

To help you adopt it incrementally under Docusaurus v3, we're introducing a set of feature flags that you can activate progressively.

We recommend turning them on all at once with this simple boolean shortcut:

const config = {
future: {
experimental_faster: true,
},
};

In case one of the flags does not work for your site, it's possible to turn feature flags on independently:

const config = {
future: {
experimental_faster: {
swcJsLoader: true,
swcJsMinimizer: true,
swcHtmlMinimizer: true,
lightningCssMinimizer: true,
rspackBundler: true,
mdxCrossCompilerCache: true,
},
},
};
Experimental but safe

Don't be afraid to turn this feature on. What's experimental is the config options.

The new infrastructure is robust and well-tested by our CI pipeline. The Docusaurus site already uses it in production, and we plan to use it on other Meta docs sites as well.

Plugins

The new infrastructure uses Rspack. By chance, Rspack is almost 100% compatible with webpack, and Rspack shouldn't break our plugin ecosystem.

Most Docusaurus plugins should work out of the box with Rspack, even those implementing configureWebpack.

However, some of them will require small modifications to make them compatible with Rspack. The general idea is to avoid importing webpack directly, and use the "dynamically provided" webpack instance instead:

-import webpack from 'webpack';

export default function (context, options) {
return {
name: 'custom-docusaurus-plugin',
- configureWebpack(config, isServer) {
+ configureWebpack(config, isServer, {currentBundler}) {
return {
plugins: [
- new webpack.DefinePlugin({}),
+ new currentBundler.instance.DefinePlugin({}),
]
};
},
};
}
For plugins authors

Check the dedicated issue for guidelines and support.

Next Steps

It's only the beginning: we will continue working on the Docusaurus Faster project and already have a few more performance improvements planned.

Depending on your feedback, we plan to make this new infrastructure the default in an upcoming major version of Docusaurus.

🙏 We'd like to thank the authors of all these great tools that already helped us make Docusaurus much faster than before. In particular the Rspack team that supported us along the way, handled our feedback very quickly and implemented all the missing features we needed to make it happen. 👏

Rsdoctor plugin

In #10588, we created a Docusaurus plugin for Rsdoctor. It analyzes the bundling phase of Docusaurus and helps you figure out what slows down the bundler in terms of loaders, plugins and minimizers. It works for both webpack and Rspack.

Loader timeline example

To use it, install the new @docusaurus/plugin-rsdoctor package, and then use the plugin in your config:

docusaurus.config.js
export default {
plugins: [
[
'rsdoctor',
{
/* options */
},
],
],
};
tip

Turn it on conditionally, based on an environment variable:

docusaurus.config.js
export default {
plugins: [
process.env.RSDOCTOR === 'true' && [
'rsdoctor',
{
/* options */
},
],
],
};
# Build without Rsdoctor
npm run build

# Build with Rsdoctor
RSDOCTOR=true npm run build

Mermaid

In #10510, we relaxed our Mermaid diagrams dependency range to allow newer major versions of Mermaid. We now support both Mermaid 10/11, and expect upcoming versions to be compatible, letting you upgrade on your own terms.

This unlocks new types of diagrams, such as Architecture Diagrams:

Translations

  • 🇸🇮 #10551: Improve Slovenian theme translations.
  • 🇻🇳 #10507: Improve Vietnamese theme translations.
  • 🇪🇸 #10413: Improve Spanish theme translations.

Other changes

Other notable changes include:

  • #10586: Blog support for frontMatter.title_meta to override frontMatter.title for SEO reason.
  • #10600: docusaurus build and docusaurus deploy now support multiple --locale CLI args.
  • #10454: docusaurus-remark-plugin-npm2yarn upgrades to npm-to-yarn v3 and can convert npx commands.
  • #10612: Canary releases will use 3.5.2-canary-<number> instead of 0.0.0-canary-<number> to respect plugins peerDependency constraints.
  • #10547: @docusaurus/tsconfig upgrades to target: 'es2022'.
  • #10514: Remove babel.config.js from Docusaurus init templates to discourage customizing Babel.

Check the 3.6.0 changelog entry for an exhaustive list of changes.

Docusaurus 3.5

· Leitura de 5 minutos
Sébastien Lorber
Docusaurus maintainer, This Week In React editor

We are happy to announce Docusaurus 3.5.

This release contains many new exciting blog features.

Upgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.

Docusaurus blog post social card

Highlights

Blog Social Icons

In #10222, we added the possibility to associate social links to blog authors, for inline authors declared in front matter or global through the authors.yml file.

blog/authors.yml
slorber:
name: Sébastien Lorber
# other author properties...
socials:
x: sebastienlorber
linkedin: sebastienlorber
github: slorber
newsletter: https://thisweekinreact.com

Author socials screenshot displaying `slorber` author with 4 social platform icons

Icons and handle shortcuts are provided for pre-defined platforms x, linkedin, github and stackoverflow. It's possible to provide any additional platform entry (like newsletter in the example above) with a full URL.

Blog Authors Pages

In #10216, we added the possibility for global blog authors (declared in authors.yml) to have their own dedicated page listing all the blog posts they contributed to.

This feature is opt-in and mostly relevant for multi-author blogs. You can turn it on for a specific author by setting the page: true property:

blog/authors.yml
slorber:
name: Sébastien Lorber
# the description will be displayed on the author's page
description: 'A freelance React and React-Native developer...'
page: true # Turns the feature on

This creates a dedicated author page at /blog/authors/slorber.

Author page screenshot for `slorber` global author

An authors index page is also created, listing all the blog authors.

Author index page listing multiple authors

Check the blog authors pages guide for details.

Blog Feeds Styling

In #9252, we added support for styling your blog feeds by providing custom XSLT .xls files for the RSS and Atom feeds. This allows browsers to render the feeds in a more visually appealing way, like a regular HTML page, instead of the default XML view.

website/docusaurus.config.js
const blogOptions = {
feedOptions: {
xslt: {
rss: 'custom-rss.xsl',
atom: 'custom-atom.xsl',
},
},
};

Writing your own XSLT can be complex, but you can also use xslt: true to turn on the built-in style:

website/docusaurus.config.js
const blogOptions = {
feedOptions: {
xslt: true,
},
};

Screenshot of the Docusaurus blog RSS feed, beautifully styled

Blog Sidebar Grouping

In #10252, we added support for grouping blog posts by years in the blog sidebar.

Screenshot of the Docusaurus blog, in particular the sidebar items grouped by year

This feature is now turned on by default, but can be disabled with themeConfig.blog.sidebar.groupByYear: false.

Blog Consistency Options

We added new blog options to enforce recommended practices for your blog posts:

onInlineAuthors

We believe large multi-blogs are easier to manage by using global authors, declared in authors.yml. This notably permits to avoids duplicating author information across multiple blog posts, and now permits to generate author pages.

In #10224, we added the onInlineAuthors option. Use onInlineAuthors: 'throw' to forbid inline authors, and enforce a consistent usage of global authors.

onUntruncatedBlogPosts

We believe blog posts are better using truncation markers (`