mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-04 01:09:20 +02:00
172 lines
6.9 KiB
Text
172 lines
6.9 KiB
Text
---
|
|
title: Docusaurus 3.6
|
|
authors: [slorber]
|
|
tags: [release]
|
|
image: ./img/social-card.png
|
|
date: 2024-10-31
|
|
---
|
|
|
|
We are happy to announce **Docusaurus 3.6**.
|
|
|
|
Docusaurus is now ⚡️⚡️⚡️ **much faster** to build your site.
|
|
|
|
Upgrading should be easy. Our [release process](/community/release-process) respects [Semantic Versioning](https://semver.org/). Minor versions do not include any breaking changes.
|
|
|
|
|
|
|
|
{/* truncate */}
|
|
|
|
## Highlights
|
|
|
|
This release has been mostly focused on build performance through the [Docusaurus Faster](https://github.com/facebook/docusaurus/issues/10556) project.
|
|
|
|
## Docusaurus Faster
|
|
|
|
The [Docusaurus Faster](https://github.com/facebook/docusaurus/issues/10556) project's goal is to reduce the build times and memory consumption.
|
|
|
|
We are modernizing our infrastructure to use modern faster Rust-based tools, notably:
|
|
|
|
- [Rspack](https://rspack.dev/): Fast Rust-based web bundler, almost drop-in replacement for [webpack](https://webpack.js.org/).
|
|
- [SWC](https://swc.rs/): Speedy Web Compiler, Rust-based platform for the Web (HTML, CSS, JS).
|
|
- [Lightning CSS](https://lightningcss.dev/): An extremely fast CSS parser, transformer, bundler, and minifier.
|
|
|
|
### Expected Impact
|
|
|
|
Benchmarks on community site show that you can expect your site to build ⚡️**~3 times faster**! 🔥
|
|
|
|
- [React Native website](https://github.com/facebook/react-native-website/pull/4268): 3.04x faster 🔥
|
|
- [Babel website](https://github.com/babel/website/pull/2997): 3.27x faster 🔥
|
|
- [Lexical website](https://github.com/facebook/lexical/pull/6761): 2x faster 🔥
|
|
|
|
### 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, you will have to install a new package that encapsulates all the modern tools:
|
|
|
|
```bash npm2yarn
|
|
npm install @docusaurus/faster
|
|
```
|
|
|
|
To help you **adopt it incrementally under Docusaurus v3**, we are releasing it as part of a set of feature flags you can turn on progressively.
|
|
|
|
We recommend turning them on all at once with this simple boolean shortcut:
|
|
|
|
```js
|
|
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:
|
|
|
|
- [`swcJsLoader`](https://github.com/facebook/docusaurus/pull/10435): Use [SWC](https://swc.rs/) to transpile JS (instead of [Babel](https://babeljs.io/)).
|
|
- [`swcJsMinimizer`](https://github.com/facebook/docusaurus/pull/10441): Use [SWC](https://swc.rs/) to minify JS (instead of [Terser](https://github.com/terser/terser)).
|
|
- [`swcHtmlMinimizer `](https://github.com/facebook/docusaurus/pull/10554): Use [SWC](https://swc.rs/) to minify HTML and inlined JS/CSS (instead of [html-minifier-terser](https://github.com/terser/html-minifier-terser)).
|
|
- [`lightningCssMinimizer`](https://github.com/facebook/docusaurus/pull/10522): Use [Lightning CSS](https://lightningcss.dev/) to minify CSS (instead of [cssnano](https://github.com/cssnano/cssnano) and [clean-css](https://github.com/clean-css/clean-css)).
|
|
- [`rspackBundler`](https://github.com/facebook/docusaurus/pull/10402): Use [Rspack](https://rspack.dev/) to bundle your app (instead of [webpack](https://webpack.js.org/)).
|
|
- [`mdxCrossCompilerCache`](https://github.com/facebook/docusaurus/pull/10479): Compile MDX files only once for both browser/Node.js environments instead of twice.
|
|
|
|
```ts
|
|
const config = {
|
|
future: {
|
|
experimental_faster: {
|
|
swcJsLoader: true,
|
|
swcJsMinimizer: true,
|
|
swcHtmlMinimizer: true,
|
|
lightningCssMinimizer: true,
|
|
rspackBundler: true,
|
|
mdxCrossCompilerCache: true,
|
|
},
|
|
},
|
|
};
|
|
```
|
|
|
|
## Rsdoctor plugin
|
|
|
|
In [#10588](https://github.com/facebook/docusaurus/pull/10588), we created a Docusaurus plugin for [Rsdoctor](https://rsdoctor.dev/). It permits to analyze the bundling phase of Docusaurus and can help you figure out what slows down the bundler in terms of loaders, plugins and minimizers. It works for both webpack and Rspack.
|
|
|
|
|
|
|
|
To use it, install the new [`@docusaurus/plugin-rsdoctor`](/docs/api/plugins/@docusaurus/plugin-rsdoctor) package, and then use the plugin in your config:
|
|
|
|
```ts title="docusaurus.config.js"
|
|
export default {
|
|
plugins: [
|
|
[
|
|
'rsdoctor',
|
|
{
|
|
/* options */
|
|
},
|
|
],
|
|
],
|
|
};
|
|
```
|
|
|
|
:::tip
|
|
|
|
Turn it on conditionally, based on an environment variable:
|
|
|
|
```ts title="docusaurus.config.js"
|
|
export default {
|
|
plugins: [
|
|
process.env.RSDOCTOR === 'true' && [
|
|
'rsdoctor',
|
|
{
|
|
/* options */
|
|
},
|
|
],
|
|
],
|
|
};
|
|
```
|
|
|
|
```bash
|
|
# Build without Rsdoctor
|
|
npm run build
|
|
|
|
# Build with Rsdoctor
|
|
RSDOCTOR=true npm run build
|
|
```
|
|
|
|
:::
|
|
|
|
## Mermaid
|
|
|
|
In [#10510](https://github.com/facebook/docusaurus/pull/10510), we relaxed our [Mermaid diagrams](https://mermaid.js.org/) 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](https://mermaid.js.org/syntax/architecture):
|
|
|
|
```mermaid
|
|
architecture-beta
|
|
group api(cloud)[API]
|
|
|
|
service db(database)[Database] in api
|
|
service disk1(disk)[Storage] in api
|
|
service disk2(disk)[Storage] in api
|
|
service server(server)[Server] in api
|
|
|
|
db:L -- R:server
|
|
disk1:T -- B:server
|
|
disk2:T -- B:db
|
|
```
|
|
|
|
## Translations
|
|
|
|
- 🇸🇮 [#10551](https://github.com/facebook/docusaurus/pull/10551): Improve Slovenian theme translations.
|
|
- 🇻🇳 [#10507](https://github.com/facebook/docusaurus/pull/10507): Improve Vietnamese theme translations.
|
|
- 🇪🇸 [#10413](https://github.com/facebook/docusaurus/pull/10413): Improve Spanish theme translations.
|
|
|
|
## Other changes
|
|
|
|
Other notable changes include:
|
|
|
|
- [#10586](https://github.com/facebook/docusaurus/pull/10586): Blog support for `frontMatter.title_meta` to override `frontMatter.title` for SEO reason.
|
|
- [#10600](https://github.com/facebook/docusaurus/pull/10600): `docusaurus build` and `docusaurus deploy` now support multiple `--locale` CLI args.
|
|
- [#10454](https://github.com/facebook/docusaurus/pull/10454): `docusaurus-remark-plugin-npm2yarn` upgrades to [`npm-to-yarn` v3](https://github.com/nebrelbug/npm-to-yarn/releases/tag/v3.0.0) and can convert `npx` commands.
|
|
- [#10612](https://github.com/facebook/docusaurus/pull/10612): Canary releases will use `3.5.2-canary-<number>` instead of `0.0.0-canary-<number>` to respect plugins `peerDependency` constraints.
|
|
- [#10547](https://github.com/facebook/docusaurus/pull/10547): `@docusaurus/tsconfig` upgrades to `target: 'es2022'`.
|
|
- [#10514](https://github.com/facebook/docusaurus/pull/10514): Remove `babel.config.js` from Docusaurus init templates to discourage customizing Babel.
|
|
|
|
Check the **[3.6.0 changelog entry](/changelog/3.6.0)** for an exhaustive list of changes.
|