跳到主要内容
Sébastien Lorber
Docusaurus 维护者、React 周刊编者

一个自由职业者,React/React-Native 开发者和 Docusaurus 维护者,生活在巴黎附近。同时在维护一个网站,ThisWeekInReact.com 。它是有关于 React 生态最新动态的通讯简报。

查看所有作者

Docusaurus 3.8

· 阅读需 11 分钟
Sébastien Lorber
Docusaurus 维护者、React 周刊编者

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,
},
};
提示

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.
提示

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.

维护

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 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

· 阅读需 3 分钟
Sébastien Lorber
Docusaurus 维护者、React 周刊编者

我们很高兴地宣布 Docusaurus 3.7 现已发布。

Docusaurus 现已完全兼容 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

精彩内容

React 19

#10763 这一个更新中,我们添加了对 React 19 的支持,Docusaurus 网站已经在 React 19 上运行。

从现在起,所有新初始化的站点默认都会在 React 19 上运行,Docusaurus v4 的最低要求版本将是 React 19 。

不过,React 18 仍然能够得到支持,现有的 Docusaurus 站点可以选择留在React 18,或者将其依赖升级到 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"
}
}
警告

无需立即升级您的网站。

React 19 要比 React 18重一点。 由于我们支持这两种版本,我们还不会对 React19 独有的功能施加影响。

然而,可以升级到 React 19 准备你的 Docusaurus v4 站点,将来可能会逐步减少 React 18 的支持。

以下是在 Docusaurus v4 之前升级您的网站的良好理由:

  • 你有自定义的 React 代码,并且想要确保它已为 React19 准备就绪
  • 您计划在自己的代码中利用新的 React 19 的特性
  • 您使用自定义或第三方插件,并且想要确保它们的兼容性
  • 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 插件

Docusaurus 内置支持 SVGR,允许您将 SVG 文件作为 React 组件无缝导入并使用:

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. 默认情况下它包含在我们经典预设中:

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

其他改变:

Other notable changes include:

  • #10768: Blog authors have built-in icons for social platforms bluesky, mastodon, threads, twitch, youtube, instagram.
  • #10729:博客现在支持 frontMatter.sidebar_label
  • #10803: @docusaurus/remark-plugin-npm2yarn 现在支持 Bun 转换
  • #10672:将 Algolia DocSearch 升级到 algoliasearch v5
  • #10800: Docusaurus Faster turns Rspack incremental mode on by default.
  • #10783:改进荷兰语的主题翻译
  • #10760:改进韩文的主题翻译

查看 3.7.0 changelog entry 以获取更详细的变更列表

Docusaurus 3.6

· 阅读需 8 分钟
Sébastien Lorber
Docusaurus 维护者、React 周刊编者

我们很高兴地宣布 Docusaurus 3.6 现已发布。

Docusaurus 现在可以⚡️⚡️⚡️: 更快的 构建你的网站。

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

Docusaurus blog post social card

精彩内容

该版本主要专注于通过 Docusaurus Faster 项目构建性能。

Docusaurus Faster

Docusaurus Faster项目的目标是减少构建时间和内存消耗。

我们致力于多个优化和使我们的基础设施现代化,以便更快地使用基于Rus的工具,特别是:

  • 🦀 Rspack: 基于Rust的快速网页打包工具, 几乎是可以作为 webpack的完全替代品
  • 🦀 SWC: 快速的网页编辑器,基于Rust的网页平台(HTML, CS, JS)
  • 🦀 Lightning CSS: 一个极为快速的 CSS 解析器、翻译器、打包工具和压缩器。

影响

采用新的基础设施可能会产生各种影响。 由于不可能将所有问题全部列举出来,因此我们将重点关注主要的几个。

为了帮助您轻松地使用它,我们在预期的静态站点输出和浏览器支持 方面相当保守。

构建时间

社区网站上的基准测试显示,您可以期待您的生产网站构建速度 ⚡️ 提高 2 到 4 倍! 🔥:

如何进行基准测试

关于重建

Rspack 目前尚不支持持久缓存,但它在开发路线图上,预计很快会实现。 我们认为,这对 Rspack 的采用并不是一个问题,因为冷启动的 Rspack 构建通常与使用持久缓存的热 Webpack 构建一样快。

内存消耗

您还应该注意到内存消耗的改进:

  • 新基础设施消耗总内存减少
  • 我们修复了一个重要的内存泄漏,它特别影响到i18n 站点
  • 我们添加了CI检查,以确保我们不会出现回归问题,并且我们的站点和初始化模版都能在内存受限的环境中构建。
  • 我们添加了内部工具以更好地理解构建的哪一步消耗内存
  • 我们移除了一个 process.exit(0),该代码可能会掩盖您自己代码和第三方插件中的内存泄漏问题。

其他影响

采用策略

这种新的基础设施是一种突破性的变化,但它是选择性的,不需要新版本的Docusaurus。

在使用 Docusaurus 更快之前,添加这个新包:

npm install @docusaurus/faster

为了帮助您在 在Docusaurus v3中逐步采用它,我们引入了一组可以逐步激活的功能标志。

我们建议通过这个简单的布尔快捷方式一次性启用它们:

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

如果其中一个功能标志不适用于您的网站,可以独立启用功能标志:

const config = {
future: {
experimental_faster: {
swcJsLoader: true,
swcJsMinimizer: true,
swcHtmlMinimizer: true,
lightningCssMinimizer: true,
rspackBundler: true,
mdxCrossCompilerCache: true,
},
},
};
实验功能但安全

不要害怕打开此功能。 配置选项是实验性的。

新的基础设施是牢固的,我们的综合基础设施管道对其进行了很好的考验。 Docusaurus网站已经在生产中使用了它,我们也计划在其他Meta文档网站上使用它。

插件

新的基础设施使用 Rspack。 碰巧的是,Rspack 与 webpack 几乎 100% 兼容,并且 Rspack 不会破坏我们的插件生态系统。

大多数Docusaurus插件都应该可以与Rspack开箱即用,即使是那些实现了configureWebpack 的插件。

然而,其中有些需要做小的修改,以使其与Rspack兼容。 一般的想法是避免直接导入 webpack ,而是使用 "动态提供" webpack 实例:

-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({}),
]
};
},
};
}
插件作者

查看专用问题获取指南和支持。

后续步骤

这是一个开端:我们将继续开发Docusaurus Faster项目,并且已经计划了一些更多的性能改进。

取决于您的反馈, 我们计划在即将到来的主要版本Docusaurus中将此新基础设施设置为默认。

🙏 我们感谢所有这些伟大工具的作者,这些工具已经帮助我们使Docusaurus比以前快得多。 特别感谢 Rspack 团队 在整个过程中对我们的支持,他们迅速处理了我们的反馈,并现了我们所需的所有缺失功能,使这一切得以顺利进行。 👏

Rsdoctor 插件

#10588中, 我们创建了一个 Rsdoctor的Docusaurus插件. 它分析了 Docusaurus 的打包阶段,帮助你找出在加载器、插件和压缩器方面导致打包速度变慢的原因。 它同时适用于webpack 和 Rspack。

加载时间轴示例

要使用它,请安装新的 @docusaurus/plugin-rsdoctor 包,然后在你的配置中使用插件:

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

基于环境变量有条件地启用它:

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

#10510 中,我们放宽了我们的 Mermaid diagrams 依赖范围以允许较新的主要版本的Mermaid。 我们现在支持 Mermaid 10 和 11,并预计即将发布的版本也将兼容,让您可以根据自己的需求进行升级。

解锁了新的图表类型,例如 架构图

Translations

  • 🇸🇮 #10551: 改进斯洛文尼亚语翻译。
  • :越南:#10507:改进越南主题翻译。
  • 🇪🇸 #10413: 改进西班牙语主题的翻译。

其他改变:

Other notable changes include:

  • #10586: 博客支持 frontMatter.title_meta 以基于SEO 的理由覆盖 frontMatter.title
  • #10600: docusaurus build and docusaurus depl 现在支持多个--locale CLI args.
  • #10454: docusaurus-mot-plugin-npm2yarn 升级到 [npmto-yarn v3](https://github.com/nebrelbug/npm-to yarn/releases/tag/v3.0.0.0) 并可以转换 npx 命令。
  • #10612:Canary releases will used 3.5.2-canary-<number> 而不是0.0.0-canary-<number> for respect plugins peerDependency
  • #10547: @docusaurus/tsconfig 升级到 `target: 'es2022'
  • #10514:从Docusaurus init 模板中删除babel.config.js,以阻止定制Babel。

查看 3.6.0 changelog entry 以获取更详细的变更列表

Docusaurus 3.5

· 阅读需 5 分钟
Sébastien Lorber
Docusaurus 维护者、React 周刊编者

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

精彩内容

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 (`