chore(deps): bump marocchino/sticky-pull-request-comment from 2.9.1 to 2.9.2 (#11103)

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.cspell.json

@@ -21,11 +21,14 @@
   ],
   "ignorePaths": [
     "CHANGELOG.md",
+    "patches",
     "packages/docusaurus-theme-translations/locales",
+    "packages/docusaurus-plugin-ideal-image/src/theme/IdealImageLegacy",
     "package.json",
     "yarn.lock",
     "project-words.txt",
     "__snapshots__",
+    "admin/scripts",
     "website/src/data/users.tsx",
     "website/src/data/tweets.tsx",
     "website/docusaurus.config.localized.json",

.devcontainer/devcontainer.json

@@ -1,32 +1,36 @@
 {
-  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-22.04",
-  "settings": {
-    "[typescript]": {
-      "editor.defaultFormatter": "esbenp.prettier-vscode",
-      "editor.formatOnSave": true
-    },
-    "[json]": {
-      "editor.defaultFormatter": "esbenp.prettier-vscode",
-      "editor.formatOnSave": true
-    },
-    "[jsonc]": {
-      "editor.defaultFormatter": "esbenp.prettier-vscode",
-      "editor.formatOnSave": true
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "[typescript]": {
+          "editor.defaultFormatter": "esbenp.prettier-vscode",
+          "editor.formatOnSave": true
+        },
+        "[json]": {
+          "editor.defaultFormatter": "esbenp.prettier-vscode",
+          "editor.formatOnSave": true
+        },
+        "[jsonc]": {
+          "editor.defaultFormatter": "esbenp.prettier-vscode",
+          "editor.formatOnSave": true
+        }
+      },
+      "extensions": [
+        "dbaeumer.vscode-eslint",
+        "orta.vscode-jest",
+        "esbenp.prettier-vscode",
+        "streetsidesoftware.code-spell-checker"
+      ]
     }
   },
-  "extensions": [
-    "dbaeumer.vscode-eslint",
-    "orta.vscode-jest",
-    "esbenp.prettier-vscode",
-    "streetsidesoftware.code-spell-checker"
-  ],
   "forwardPorts": [3000],
   "containerUser": "vscode",
   "postCreateCommand": "yarn install",
   "waitFor": "postCreateCommand", // otherwise automated jest tests fail
   "features": {
     "node": {
-      "version": "18"
+      "version": "22"
     },
     "github-cli": "latest"
   }

.eslintignore

@@ -21,3 +21,7 @@ packages/create-docusaurus/lib/*
 packages/create-docusaurus/templates/facebook
 
 website/_dogfooding/_swizzle_theme_tests
+website/_dogfooding/_asset-tests/badSyntax.js
+
+
+packages/docusaurus-plugin-ideal-image/src/theme/IdealImageLegacy

.eslintrc.js

@@ -60,6 +60,7 @@ module.exports = {
   },
   reportUnusedDisableDirectives: true,
   plugins: [
+    'react-compiler',
     'react-hooks',
     'header',
     'jest',
@@ -68,6 +69,7 @@ module.exports = {
     '@docusaurus',
   ],
   rules: {
+    'react-compiler/react-compiler': ERROR,
     'react/jsx-uses-react': OFF, // JSX runtime: automatic
     'react/react-in-jsx-scope': OFF, // JSX runtime: automatic
     'array-callback-return': WARNING,
@@ -296,7 +298,7 @@ module.exports = {
     'jest/expect-expect': OFF,
     'jest/no-large-snapshots': [
       WARNING,
-      {maxSize: Infinity, inlineMaxSize: 10},
+      {maxSize: Infinity, inlineMaxSize: 50},
     ],
     'jest/no-test-return-statement': ERROR,
     'jest/prefer-expect-resolves': WARNING,
@@ -380,7 +382,14 @@ module.exports = {
     // We don't provide any escape hatches for this rule. Rest siblings and
     // function placeholder params are always ignored, and any other unused
     // locals must be justified with a disable comment.
-    '@typescript-eslint/no-unused-vars': [ERROR, {ignoreRestSiblings: true}],
+    '@typescript-eslint/no-unused-vars': [
+      ERROR,
+      {
+        ignoreRestSiblings: true,
+        argsIgnorePattern: '^_',
+        varsIgnorePattern: '^_',
+      },
+    ],
     '@typescript-eslint/prefer-optional-chain': ERROR,
     '@docusaurus/no-html-links': ERROR,
     '@docusaurus/prefer-docusaurus-heading': ERROR,
@@ -396,6 +405,7 @@ module.exports = {
           '@',
           'WebContainers',
           'Twitter',
+          'X',
           'GitHub',
           'Dev.to',
           '1.x',

.github/workflows/argos.yml

@@ -30,18 +30,18 @@ jobs:
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
 
       - name: Use Node.js
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: 20
+          node-version: lts/*
 
       - name: Install dependencies
-        run: yarn install --frozen-lockfile
+        run: yarn || yarn || yarn
 
       - name: Install Playwright browsers
         run: npx playwright install --with-deps chromium
 
       - name: Build website fast
-        run: yarn build:website:fast --dev
+        run: yarn argos:build
 
       - name: Take Argos screenshots
         run: yarn argos:screenshot

.github/workflows/build-blog-only.yml

@@ -24,11 +24,11 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: 20
+          node-version: lts/*
           cache: yarn
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
       - name: Build blog-only
         run: yarn workspace website build:blogOnly

.github/workflows/build-hash-router.yml

@@ -27,12 +27,12 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: '18'
+          node-version: lts/*
           cache: yarn
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
 
       - name: Build Hash Router
         run: yarn build:website:fast

.github/workflows/build-perf.yml

@@ -11,6 +11,7 @@ on:
       - main
       - docusaurus-v**
     paths:
+      - .github/workflows/build-perf.yml
       - package.json
       - yarn.lock
       - packages/**
@@ -25,6 +26,7 @@ permissions:
   contents: read
 
 jobs:
+  # Posts a PR comment with build size differences from PR vs main branches
   build-size:
     permissions:
       checks: write # for preactjs/compressed-size-action to create and update the checks
@@ -34,47 +36,65 @@ jobs:
     name: Build Size Report
     timeout-minutes: 30
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        DOCUSAURUS_INFRA: ['SLOWER', 'FASTER']
     steps:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: 20
+          node-version: lts/*
           cache: yarn
       - name: Track build size changes
-        uses: preactjs/compressed-size-action@f780fd104362cfce9e118f9198df2ee37d12946c # v2
+        uses: preactjs/compressed-size-action@946a292cd35bd1088e0d7eb92b69d1a8d5b5d76a # v2
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           build-script: build:website:fast
           clean-script: clear:website # see https://github.com/facebook/docusaurus/pull/6838
-          pattern: '{website/build/assets/js/main*js,website/build/assets/css/styles*css,website/.docusaurus/globalData.json,website/.docusaurus/registry.js,website/.docusaurus/routes.js,website/.docusaurus/routesChunkNames.json,website/.docusaurus/site-metadata.json,website/.docusaurus/codeTranslations.json,website/.docusaurus/i18n.json,website/.docusaurus/docusaurus.config.mjs,website/build/index.html,website/build/docs.html,website/build/docs/**/*.html,website/build/blog.html,website/build/blog/**/*.html}'
+          pattern: '{website/build/assets/js/main*js,website/build/assets/js/runtime~main*js,website/build/assets/css/styles*css,website/.docusaurus/globalData.json,website/.docusaurus/registry.js,website/.docusaurus/routes.js,website/.docusaurus/routesChunkNames.json,website/.docusaurus/site-metadata.json,website/.docusaurus/codeTranslations.json,website/.docusaurus/i18n.json,website/.docusaurus/docusaurus.config.mjs,website/build/index.html,website/build/docs.html,website/build/docs/**/*.html,website/build/blog.html,website/build/blog/**/*.html}'
           # HTML files: exclude versioned docs pages, tags pages, html redirect files
           exclude: '{website/build/docs/?.?.?/**/*.html,website/build/docs/next/**/*.html,website/build/blog/tags/**/*.html,**/*.html.html}'
           strip-hash: '\.([^;]\w{7})\.'
           minimum-change-threshold: 30
           compression: none
+          comment-key: DOCUSAURUS_INFRA_${{ matrix.DOCUSAURUS_INFRA }}
+        env:
+          DOCUSAURUS_SLOWER: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 'true' || 'false'  }}
+
+  # Ensures build times stay under reasonable thresholds
   build-time:
     name: Build Time Perf
     timeout-minutes: 30
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        DOCUSAURUS_INFRA: ['SLOWER', 'FASTER']
     steps:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
+          node-version: lts/*
           cache: yarn
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
 
       # Ensure build with a cold cache does not increase too much
       - name: Build (cold cache)
         run: yarn build:website:fast
-        timeout-minutes: 8
+        timeout-minutes: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 3 || 2  }}
+        env:
+          DOCUSAURUS_SLOWER: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 'true' || 'false'  }}
 
       # Ensure build with a warm cache does not increase too much
       - name: Build (warm cache)
         run: yarn build:website:fast
-        timeout-minutes: 2
+        # Temporary: upper value for Rspack until incremental cache works better
+        timeout-minutes: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 1 || 2  }}
+        env:
+          DOCUSAURUS_SLOWER: ${{ matrix.DOCUSAURUS_INFRA == 'SLOWER' && 'true' || 'false'  }}
+
     # TODO post a GitHub comment with build with perf warnings?

.github/workflows/canary-release.yml

@@ -1,11 +1,14 @@
 name: Canary Release
 
 on:
+  workflow_dispatch:
   push:
     branches:
       - main
       - docusaurus-v**
     paths:
+      - .github/workflows/canary-release.yml
+      - package.json
       - packages/**
 
 permissions:
@@ -21,9 +24,9 @@ jobs:
         with:
           fetch-depth: 0 # Needed to get the commit number with "git rev-list --count HEAD"
       - name: Set up Node
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: 20
+          node-version: lts/*
           cache: yarn
       - name: Prepare git
         run: |
@@ -38,7 +41,7 @@ jobs:
         env:
           NPM_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
       - name: Publish Canary release
         run: |
           yarn canary

.github/workflows/codeql-analysis.yml

@@ -36,9 +36,9 @@ jobs:
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@eb055d739abdc2e8de2e5f4ba1a8b246daa779aa # 3.26.0
+        uses: github/codeql-action/init@2c779ab0d087cd7fe7b826087247c2c81f27bfa6 # 3.26.5
         with:
           languages: ${{ matrix.language }}
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@eb055d739abdc2e8de2e5f4ba1a8b246daa779aa # 3.26.0
+        uses: github/codeql-action/analyze@2c779ab0d087cd7fe7b826087247c2c81f27bfa6 # 3.26.5

.github/workflows/continuous-releases.yml

@@ -20,8 +20,14 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
 
+      - name: Set up Node
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: lts/*
+          cache: yarn
+
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
 
       - name: Build packages
         run: yarn build:packages
@@ -32,4 +38,4 @@ jobs:
           yarn create-docusaurus template/docusaurus-classic-ts classic --typescript -p npm
 
       - name: Release
-        run: npx pkg-pr-new publish './packages/*' --template './template/*' --compact --comment=off
+        run: npx pkg-pr-new@0.0.20 publish './packages/*' --template './template/*' --compact --comment=off

.github/workflows/dependency-review.yml

@@ -15,4 +15,4 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Dependency Review
-        uses: actions/dependency-review-action@5a2ce3f5b92ee19cbb1541a4984c76d921601d7c # 4.3.4
+        uses: actions/dependency-review-action@ce3cf9537a52e8119d91fd484ab5b8a807627bf8 # 4.6.0

.github/workflows/lighthouse-report.yml

@@ -24,12 +24,12 @@ jobs:
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
 
       - name: Use Node.js
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: 20
+          node-version: lts/*
 
       - name: Install dependencies
-        run: yarn install --frozen-lockfile
+        run: yarn || yarn || yarn
 
       - name: Build website fast
         run: yarn build:website:fast
@@ -64,7 +64,7 @@ jobs:
 
       - name: Add Lighthouse stats as comment
         id: comment_to_pr
-        uses: marocchino/sticky-pull-request-comment@331f8f5b4215f0445d3c07b4967662a32a2d3e31 # 2.9.0
+        uses: marocchino/sticky-pull-request-comment@67d0dec7b07ed060a405f9b2a64b8ab319fdd7db # 2.9.2
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           number: ${{ github.event.pull_request.number }}

.github/workflows/lint-autofix.yml

@@ -25,7 +25,7 @@ jobs:
           ref: ${{ github.head_ref }}
 
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
 
       - name: AutoFix Format
         run: yarn format

.github/workflows/lint.yml

@@ -22,19 +22,18 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: 20
+          node-version: lts/*
           cache: yarn
       - name: Installation
-        run: yarn
-        # run: yarn install --immutable # Fails if yarn.lock is modified (unfortunately only works for Yarn 2, and --frozen-lockfile is not the same!)
+        run: yarn install --frozen-lockfile || yarn install --frozen-lockfile || yarn install --frozen-lockfile
       - name: Check immutable yarn.lock
         run: git diff --exit-code
 
       - name: Check for suspicious yarn.lock
         # for allowed aliases, see https://github.com/yargs/cliui/pull/139/files#r1670711112
-        run: yarn lockfile-lint --path yarn.lock --type yarn --allowed-hosts yarn --validate-https --validate-package-names --validate-integrity --empty-hostname=false --allowed-package-name-aliases react-loadable string-width-cjs strip-ansi-cjs wrap-ansi-cjs
+        run: yarn lockfile-lint --path yarn.lock --type yarn --allowed-hosts yarn --validate-https --validate-package-names --validate-integrity --empty-hostname=false --allowed-package-name-aliases react-loadable react-helmet-async string-width-cjs strip-ansi-cjs wrap-ansi-cjs
 
       - name: Lint
         run: |

.github/workflows/showcase-test.yml

@@ -24,11 +24,11 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: 20
+          node-version: lts/*
           cache: yarn
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
       - name: Test
         run: yarn test website/src/data/__tests__/user.test.ts

.github/workflows/tests-e2e.yml

@@ -38,21 +38,21 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: ['18.0', '20', '22.4']
+        node: ['18.0', '20', '22']
     steps:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: ${{ matrix.node }}
           cache: yarn
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
       - name: Generate test-website project against main branch
         run: yarn test:build:website -s
       - name: Install test-website project with Yarn v1
-        run: yarn install
+        run: yarn || yarn || yarn
         working-directory: ../test-website
         env:
           npm_config_registry: http://localhost:4873
@@ -62,7 +62,14 @@ jobs:
         env:
           E2E_TEST: true
       - name: Build test-website project
-        run: yarn build
+        # We build 2 locales to ensure a localized site doesn't leak memory
+        # See https://github.com/facebook/docusaurus/pull/10599
+        run: yarn build --locale en --locale fr
+        env:
+          # Our website should build even with limited memory
+          # See https://github.com/facebook/docusaurus/pull/10590
+          NODE_OPTIONS: '--max-old-space-size=300'
+          DOCUSAURUS_PERF_LOGGER: 'true'
         working-directory: ../test-website
 
   yarn-berry:
@@ -77,12 +84,12 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Use Node.js LTS
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: lts/*
           cache: yarn
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
       - name: Generate test-website project with ${{ matrix.variant }} against main branch
         run: yarn test:build:website ${{ matrix.variant }}
       - name: Install test-website project with Yarn Berry and nodeLinker = ${{ matrix.nodeLinker }}
@@ -98,7 +105,7 @@ jobs:
           # https://yarnpkg.com/features/pnp#fallback-mode
           yarn config set pnpFallbackMode none
 
-          yarn install
+          yarn || yarn || yarn
         working-directory: ../test-website
         env:
           YARN_ENABLE_IMMUTABLE_INSTALLS: false # Yarn berry should create the lockfile, despite CI env
@@ -128,7 +135,14 @@ jobs:
           yarn typecheck
 
       - name: Build test-website project
-        run: yarn build
+        # We build 2 locales to ensure a localized site doesn't leak memory
+        # See https://github.com/facebook/docusaurus/pull/10599
+        run: yarn build --locale en --locale fr
+        env:
+          # Our website should build even with limited memory
+          # See https://github.com/facebook/docusaurus/pull/10590
+          NODE_OPTIONS: '--max-old-space-size=300'
+          DOCUSAURUS_PERF_LOGGER: 'true'
         working-directory: ../test-website
 
   npm:
@@ -139,26 +153,36 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Use Node.js LTS
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: lts/*
           cache: yarn
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
       - name: Generate test-website project against main branch
-        run: yarn test:build:website -s
+        run: yarn test:build:website -st
       - name: Install test-website project with npm
         run: npm install
         working-directory: ../test-website
         env:
           npm_config_registry: http://localhost:4873
+      - name: TypeCheck website
+        working-directory: ../test-website
+        run: yarn typecheck
       - name: Start test-website project
         run: npm run start -- --no-open
         working-directory: ../test-website
         env:
           E2E_TEST: true
       - name: Build test-website project
-        run: npm run build
+        # We build 2 locales to ensure a localized site doesn't leak memory
+        # See https://github.com/facebook/docusaurus/pull/10599
+        run: npm run build -- --locale en --locale fr
+        env:
+          # Our website should build even with limited memory
+          # See https://github.com/facebook/docusaurus/pull/10590
+          NODE_OPTIONS: '--max-old-space-size=300'
+          DOCUSAURUS_PERF_LOGGER: 'true'
         working-directory: ../test-website
 
   pnpm:
@@ -169,27 +193,36 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Use Node.js LTS
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: lts/*
           cache: yarn
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
       - name: Generate test-website project against main branch
-        run: yarn test:build:website -s
+        run: yarn test:build:website -st
       - name: Install test-website project with pnpm
         run: |
           npm install -g pnpm
-          # Fix some peer dependencies errors
-          pnpm add @algolia/client-search @types/react@17 typescript
+          pnpm install
         working-directory: ../test-website
         env:
           npm_config_registry: http://localhost:4873
+      - name: TypeCheck website
+        working-directory: ../test-website
+        run: yarn typecheck
       - name: Start test-website project
         run: pnpm start --no-open
         working-directory: ../test-website
         env:
           E2E_TEST: true
       - name: Build test-website project
-        run: pnpm run build
+        # We build 2 locales to ensure a localized site doesn't leak memory
+        # See https://github.com/facebook/docusaurus/pull/10599
+        run: pnpm run build --locale en --locale fr
+        env:
+          # Our website should build even with limited memory
+          # See https://github.com/facebook/docusaurus/pull/10590
+          NODE_OPTIONS: '--max-old-space-size=300'
+          DOCUSAURUS_PERF_LOGGER: 'true'
         working-directory: ../test-website

.github/workflows/tests-swizzle.yml

@@ -28,12 +28,12 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Node LTS
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: lts/*
           cache: yarn
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
 
       # Swizzle all the theme components
       - name: Swizzle (${{matrix.action}} - ${{matrix.variant}})
@@ -43,4 +43,4 @@ jobs:
         run: yarn build:website:fast
       # Ensure swizzled site still typechecks
       - name: TypeCheck website
-        run: yarn workspace website typecheck
+        run: yarn workspace website typecheck --project tsconfig.skipLibCheck.json

.github/workflows/tests-windows.yml

@@ -27,18 +27,18 @@ jobs:
     runs-on: windows-latest
     strategy:
       matrix:
-        node: ['18.0', '20', '22.4']
+        node: ['18.0', '20', '22']
     steps:
       - name: Support longpaths
         run: git config --system core.longpaths true
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: ${{ matrix.node }}
       - name: Installation
-        run: yarn || yarn || yarn # 3 attempts to avoid timeout errors...
+        run: yarn || yarn || yarn
       - name: Docusaurus Jest Tests
         run: yarn test
       - name: Create a deep path
@@ -55,12 +55,16 @@ jobs:
         run: yarn build:website:fast
 
       - name: TypeCheck website
-        run: yarn workspace website typecheck
+        # TODO temporary, remove TS skipLibCheck
+        # see https://github.com/facebook/docusaurus/pull/10486
+        run: yarn workspace website typecheck --project tsconfig.skipLibCheck.json
       - name: TypeCheck website - min version - v5.1
         run: |
           yarn add typescript@5.1.6 --exact -D -W --ignore-scripts
           yarn workspace website typecheck
       - name: TypeCheck website - max version - Latest
+        # For latest TS there are often lib check errors, so we disable it
+        # Details: https://github.com/facebook/docusaurus/pull/10486
         run: |
           yarn add typescript@latest --exact -D -W --ignore-scripts
-          yarn workspace website typecheck
+          yarn workspace website typecheck --project tsconfig.skipLibCheck.json

.github/workflows/tests.yml

@@ -27,31 +27,44 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: ['18.0', '20', '22.4']
+        node: ['18.0', '20', '22']
     steps:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Use Node.js ${{ matrix.node }}
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: ${{ matrix.node }}
           cache: yarn
       - name: Installation
-        run: yarn
+        run: yarn || yarn || yarn
       - name: Test
         run: yarn test
       - name: Remove Theme Internal Re-export
         run: yarn workspace @docusaurus/theme-common removeThemeInternalReexport
       - name: Docusaurus Build
-        run: yarn build:website:fast
+        # We build 2 locales to ensure a localized site doesn't leak memory
+        # See https://github.com/facebook/docusaurus/pull/10599
+        run: yarn build:website:fast --locale en --locale fr
+        env:
+          # Our website should build even with limited memory
+          # See https://github.com/facebook/docusaurus/pull/10590
+          NODE_OPTIONS: '--max-old-space-size=450'
+          DOCUSAURUS_PERF_LOGGER: 'true'
+      - name: Docusaurus site CSS order
+        run: yarn workspace website test:css-order
 
       - name: TypeCheck website
-        run: yarn workspace website typecheck
+        # TODO temporary, remove TS skipLibCheck
+        # see https://github.com/facebook/docusaurus/pull/10486
+        run: yarn workspace website typecheck --project tsconfig.skipLibCheck.json
       - name: TypeCheck website - min version - v5.1
         run: |
           yarn add typescript@5.1.6 --exact -D -W --ignore-scripts
           yarn workspace website typecheck
       - name: TypeCheck website - max version - Latest
+        # For latest TS there are often lib check errors, so we disable it
+        # Details: https://github.com/facebook/docusaurus/pull/10486
         run: |
           yarn add typescript@latest --exact -D -W --ignore-scripts
-          yarn workspace website typecheck
+          yarn workspace website typecheck --project tsconfig.skipLibCheck.json

.gitignore

@@ -14,7 +14,7 @@ package-lock.json
 .eslintcache
 
 yarn-error.log
-build
+website/build
 coverage
 .docusaurus
 .cache-loader
@@ -38,8 +38,13 @@ website/_dogfooding/_swizzle_theme_tests
 
 CrowdinTranslations_*.zip
 
+website/.cpu-prof
+
 website/i18n/**/*
 #!website/i18n/fr
 #!website/i18n/fr/**/*
 
 .netlify
+
+website/rspack-tracing.json
+website/bundler-cpu-profile.json

.prettierignore

@@ -4,6 +4,7 @@ node_modules
 build
 coverage
 .docusaurus
+.idea
 
 .svg
 *.svg
@@ -29,3 +30,5 @@ website/static/katex/katex.min.css
 
 website/changelog
 website/_dogfooding/_swizzle_theme_tests
+website/_dogfooding/_asset-tests/badSyntax.js
+website/_dogfooding/_asset-tests/badSyntax.css

.stylelintignore

@@ -13,5 +13,6 @@ packages/docusaurus-*/lib/*
 packages/create-docusaurus/lib/*
 packages/create-docusaurus/templates/
 website/static/katex/katex.min.css
+website/_dogfooding/_asset-tests/badSyntax.css
 
 jest/vendor

CHANGELOG.md

@@ -1,5 +1,351 @@
 # Docusaurus Changelog
 
+## 3.7.0 (2025-01-03)
+
+#### :rocket: New Feature
+
+- `docusaurus-faster`, `docusaurus`
+  - [#10800](https://github.com/facebook/docusaurus/pull/10800) feat(core): Turn Rspack incremental on by default (again) ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-content-blog`, `docusaurus-theme-classic`
+  - [#10768](https://github.com/facebook/docusaurus/pull/10768) feat(blog): Add author social icons for bluesky, mastodon, threads, twitch, youtube, instagram ([@GingerGeek](https://github.com/GingerGeek))
+- `create-docusaurus`, `docusaurus-mdx-loader`, `docusaurus-module-type-aliases`, `docusaurus-plugin-client-redirects`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-debug`, `docusaurus-plugin-google-analytics`, `docusaurus-plugin-google-gtag`, `docusaurus-plugin-google-tag-manager`, `docusaurus-plugin-ideal-image`, `docusaurus-plugin-pwa`, `docusaurus-plugin-rsdoctor`, `docusaurus-plugin-sitemap`, `docusaurus-plugin-svgr`, `docusaurus-plugin-vercel-analytics`, `docusaurus-preset-classic`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-mermaid`, `docusaurus-theme-search-algolia`, `docusaurus-types`, `docusaurus`
+  - [#10763](https://github.com/facebook/docusaurus/pull/10763) feat: Add React 19 support to Docusaurus v3 ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-content-blog`
+  - [#10729](https://github.com/facebook/docusaurus/pull/10729) feat(blog): Add `frontMatter.sidebar_label` ([@slorber](https://github.com/slorber))
+- `docusaurus-module-type-aliases`, `docusaurus-plugin-svgr`, `docusaurus-preset-classic`, `docusaurus-types`, `docusaurus-utils`, `docusaurus`
+  - [#10677](https://github.com/facebook/docusaurus/pull/10677) feat(svgr): create new Docusaurus SVGR plugin ([@slorber](https://github.com/slorber))
+
+#### :bug: Bug Fix
+
+- `docusaurus-remark-plugin-npm2yarn`
+  - [#10803](https://github.com/facebook/docusaurus/pull/10803) fix(npm-to-yarn): add missing npm-to-yarn converter for Bun ([@Lehoczky](https://github.com/Lehoczky))
+- `docusaurus-theme-classic`, `docusaurus-theme-common`
+  - [#10796](https://github.com/facebook/docusaurus/pull/10796) fix(theme): Footer Column/Link should merge provided className ([@slorber](https://github.com/slorber))
+- `docusaurus-bundler`, `docusaurus-theme-common`
+  - [#10786](https://github.com/facebook/docusaurus/pull/10786) fix(core): fix React hydration errors, change html minifier settings ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-common`
+  - [#10782](https://github.com/facebook/docusaurus/pull/10782) fix(theme-common): code block magic comments should support SQL block comments ([@WillBlack403](https://github.com/WillBlack403))
+- `docusaurus-theme-translations`
+  - [#10783](https://github.com/facebook/docusaurus/pull/10783) fix(theme-translations): Add missing Dutch (nl) theme translations ([@janaukema](https://github.com/janaukema))
+  - [#10760](https://github.com/facebook/docusaurus/pull/10760) fix(theme-translation): add missing Korean (ko) theme translations ([@effozen](https://github.com/effozen))
+- `docusaurus-plugin-content-docs`
+  - [#10754](https://github.com/facebook/docusaurus/pull/10754) fix(docs): fix sidebar item visibility bug for category index ([@slorber](https://github.com/slorber))
+- `docusaurus`
+  - [#10727](https://github.com/facebook/docusaurus/pull/10727) fix(core): fix codegen routesChunkName possible hash collision ([@slorber](https://github.com/slorber))
+- `docusaurus-mdx-loader`
+  - [#10723](https://github.com/facebook/docusaurus/pull/10723) fix(mdx-loader): fix md image paths with spaces bug related to transformImage encoding problem ([@slorber](https://github.com/slorber))
+
+#### :memo: Documentation
+
+- [#10740](https://github.com/facebook/docusaurus/pull/10740) docs: Link initialization docs together ([@waldyrious](https://github.com/waldyrious))
+
+#### :robot: Dependencies
+
+- [#10771](https://github.com/facebook/docusaurus/pull/10771) chore(deps): bump nanoid from 3.3.7 to 3.3.8 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- [#10721](https://github.com/facebook/docusaurus/pull/10721) chore(deps): bump actions/dependency-review-action from 4.4.0 to 4.5.0 ([@dependabot[bot]](https://github.com/apps/dependabot))
+
+#### :wrench: Maintenance
+
+- Other
+  - [#10770](https://github.com/facebook/docusaurus/pull/10770) chore: Devcontainer upgrade to Ubuntu Noble & Node 22 ([@GingerGeek](https://github.com/GingerGeek))
+- `docusaurus-theme-search-algolia`
+  - [#10801](https://github.com/facebook/docusaurus/pull/10801) refactor(algolia): simplify SearchBar component ([@slorber](https://github.com/slorber))
+  - [#10672](https://github.com/facebook/docusaurus/pull/10672) chore(algolia): upgrade algoliasearch to v5 ([@millotp](https://github.com/millotp))
+- `docusaurus`
+  - [#10798](https://github.com/facebook/docusaurus/pull/10798) refactor(core): Use Intl native API to get locale direction, remove rtl-detect depend… ([@slorber](https://github.com/slorber))
+  - [#10747](https://github.com/facebook/docusaurus/pull/10747) refactor(core): swizzle wrap should use ReactNode instead of JSX.Element ([@slorber](https://github.com/slorber))
+- `create-docusaurus`, `docusaurus-mdx-loader`, `docusaurus-module-type-aliases`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-plugin-debug`, `docusaurus-plugin-ideal-image`, `docusaurus-plugin-pwa`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-live-codeblock`, `docusaurus-theme-mermaid`, `docusaurus-theme-search-algolia`, `docusaurus-types`, `docusaurus`
+  - [#10746](https://github.com/facebook/docusaurus/pull/10746) refactor: prepare types for React 19 ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-common`
+  - [#10728](https://github.com/facebook/docusaurus/pull/10728) refactor(theme-common): change storageUtils useSyncExternalCode getSnapshot workaround ([@slorber](https://github.com/slorber))
+
+#### Committers: 14
+
+- Alvin Bryan ([@alvinometric](https://github.com/alvinometric))
+- Hichem Fantar ([@hichemfantar](https://github.com/hichemfantar))
+- Ivan Cheban ([@ivancheban](https://github.com/ivancheban))
+- Jake Boone ([@jakeboone02](https://github.com/jakeboone02))
+- Jan Aukema ([@janaukema](https://github.com/janaukema))
+- Lehoczky Zoltán ([@Lehoczky](https://github.com/Lehoczky))
+- Lin Huang ([@codimiracle](https://github.com/codimiracle))
+- Pierre Millot ([@millotp](https://github.com/millotp))
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+- Taylor Reece ([@taylorreece](https://github.com/taylorreece))
+- Waldir Pimenta ([@waldyrious](https://github.com/waldyrious))
+- William Black ([@WillBlack403](https://github.com/WillBlack403))
+- Zed Spencer-Milnes ([@GingerGeek](https://github.com/GingerGeek))
+- Zen ([@effozen](https://github.com/effozen))
+
+## 3.6.3 (2024-11-22)
+
+#### :bug: Bug Fix
+
+- `docusaurus`
+  - [#10712](https://github.com/facebook/docusaurus/pull/10712) fix(core): disable Rspack incremental in dev ([@slorber](https://github.com/slorber))
+
+#### Committers: 1
+
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+
+## 3.6.2 (2024-11-19)
+
+#### :bug: Bug Fix
+
+- `docusaurus-module-type-aliases`
+  - [#10693](https://github.com/facebook/docusaurus/pull/10693) fix(types): add missing ambiant TS declarations for .md / .mdx partials ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-translations`
+  - [#10688](https://github.com/facebook/docusaurus/pull/10688) fix(theme-translation): add and update Japanese translations ([@Ryoga-exe](https://github.com/Ryoga-exe))
+- `docusaurus`
+  - [#10685](https://github.com/facebook/docusaurus/pull/10685) fix(cli): `docusaurus --help` should print plugin commands using `extendCli()` ([@slorber](https://github.com/slorber))
+- `docusaurus-bundler`
+  - [#10680](https://github.com/facebook/docusaurus/pull/10680) fix(bundler): allow CSS nesting by default, restore postcss-preset-env ([@slorber](https://github.com/slorber))
+- `create-docusaurus`
+  - [#10676](https://github.com/facebook/docusaurus/pull/10676) fix(create-docusaurus): add ts exclude to TS init template ([@slorber](https://github.com/slorber))
+- `docusaurus-bundler`, `docusaurus-faster`, `docusaurus`
+  - [#10648](https://github.com/facebook/docusaurus/pull/10648) fix(faster): Upgrade to Rspack 1.1.1, fix build progress bar display ([@slorber](https://github.com/slorber))
+
+#### :wrench: Maintenance
+
+- [#10691](https://github.com/facebook/docusaurus/pull/10691) chore(ci): retry `yarn install` to ignore temporary network errors ([@slorber](https://github.com/slorber))
+
+#### Committers: 5
+
+- Junior_Gx ([@goffxnca](https://github.com/goffxnca))
+- Kyle Tsang ([@kyletsang](https://github.com/kyletsang))
+- Ryoga ([@Ryoga-exe](https://github.com/Ryoga-exe))
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+- Zwyx ([@Zwyx](https://github.com/Zwyx))
+
+## 3.6.1 (2024-11-08)
+
+#### :bug: Bug Fix
+
+- `docusaurus`
+  - [#10658](https://github.com/facebook/docusaurus/pull/10658) fix(core): bundler should not minimize static assets ([@slorber](https://github.com/slorber))
+- `docusaurus-bundler`, `docusaurus-faster`, `docusaurus-utils-common`, `docusaurus-utils`
+  - [#10649](https://github.com/facebook/docusaurus/pull/10649) fix(faster,utils): fix faster/types peerDependencies ([@slorber](https://github.com/slorber))
+
+#### :nail_care: Polish
+
+- `docusaurus-bundler`, `docusaurus-types`, `docusaurus`
+  - [#10655](https://github.com/facebook/docusaurus/pull/10655) refactor(faster,bundler,core): improve js loader DX ([@slorber](https://github.com/slorber))
+
+#### :memo: Documentation
+
+- [#10657](https://github.com/facebook/docusaurus/pull/10657) docs: fix old base ts config ref ([@slorber](https://github.com/slorber))
+
+#### :wrench: Maintenance
+
+- `docusaurus-mdx-loader`
+  - [#10651](https://github.com/facebook/docusaurus/pull/10651) refactor(mdx-loader): streamline typescript usage for remark plugin types ([@lebalz](https://github.com/lebalz))
+- Other
+  - [#10650](https://github.com/facebook/docusaurus/pull/10650) chore: Argos screenshot dogfooding test pages ([@slorber](https://github.com/slorber))
+
+#### Committers: 2
+
+- Balthasar Hofer ([@lebalz](https://github.com/lebalz))
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+
+## 3.6.0 (2024-11-04)
+
+#### :rocket: New Feature
+
+- `docusaurus-plugin-content-blog`, `docusaurus-theme-classic`
+  - [#10586](https://github.com/facebook/docusaurus/pull/10586) feat(blog): Add `frontMatter.title_meta` to override title for SEO ([@ilg-ul](https://github.com/ilg-ul))
+- `docusaurus`
+  - [#10600](https://github.com/facebook/docusaurus/pull/10600) feat(cli): build/deploy should allow multiple `--locale` options ([@slorber](https://github.com/slorber))
+- `docusaurus-logger`
+  - [#10590](https://github.com/facebook/docusaurus/pull/10590) feat(core): add Node.js memory perf logging ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-rsdoctor`
+  - [#10588](https://github.com/facebook/docusaurus/pull/10588) feat: new Rsdoctor official plugin ([@slorber](https://github.com/slorber))
+- `docusaurus-bundler`, `docusaurus-faster`, `docusaurus-theme-classic`, `docusaurus`
+  - [#10402](https://github.com/facebook/docusaurus/pull/10402) feat(core): Replace Webpack with Rspack - `siteConfig.future.experimental_faster.rspackBundler` ([@slorber](https://github.com/slorber))
+- `docusaurus-bundler`, `docusaurus-faster`, `docusaurus-types`, `docusaurus`
+  - [#10554](https://github.com/facebook/docusaurus/pull/10554) feat(core): faster HTML minimizer - `siteConfig.future.experimental_faster.swcHtmlMinimizer` ([@slorber](https://github.com/slorber))
+  - [#10522](https://github.com/facebook/docusaurus/pull/10522) feat(core): faster CSS minimizer - `siteConfig.future.experimental_faster.lightningCssMinimizer` ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-mermaid`
+  - [#10510](https://github.com/facebook/docusaurus/pull/10510) feat(theme-mermaid): support Mermaid 11+ including new types of diagrams ([@slorber](https://github.com/slorber))
+- `docusaurus-mdx-loader`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus-types`, `docusaurus`
+  - [#10479](https://github.com/facebook/docusaurus/pull/10479) feat(core, mdx-loader): deduplicate MDX compilation - `siteConfig.future.experimental_faster.mdxCrossCompilerCache` ([@slorber](https://github.com/slorber))
+- `docusaurus-faster`, `docusaurus-types`, `docusaurus`
+  - [#10441](https://github.com/facebook/docusaurus/pull/10441) feat(core): faster JS minimizer - `siteConfig.future.experimental_faster.swcJsMinimizer` ([@slorber](https://github.com/slorber))
+- `docusaurus-faster`, `docusaurus-plugin-content-docs`, `docusaurus-types`, `docusaurus`
+  - [#10435](https://github.com/facebook/docusaurus/pull/10435) feat(core): faster transpiler option - `siteConfig.future.experimental_faster.swcJsLoader` ([@slorber](https://github.com/slorber))
+
+#### :bug: Bug Fix
+
+- `docusaurus-bundler`, `docusaurus`
+  - [#10632](https://github.com/facebook/docusaurus/pull/10632) fix(core): restore Rspack ProgressBar colors ([@slorber](https://github.com/slorber))
+  - [#10581](https://github.com/facebook/docusaurus/pull/10581) fix(core): fix handling of Swc html minifier warnings ([@slorber](https://github.com/slorber))
+  - [#10573](https://github.com/facebook/docusaurus/pull/10573) fix(core): move @docusaurus/faster to bundler peerDeps ([@slorber](https://github.com/slorber))
+- `docusaurus-bundler`
+  - [#10617](https://github.com/facebook/docusaurus/pull/10617) fix(faster): allow Rspack + babel-loader ([@slorber](https://github.com/slorber))
+  - [#10614](https://github.com/facebook/docusaurus/pull/10614) fix(faster): fix error message typo + add color ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-classic`
+  - [#10618](https://github.com/facebook/docusaurus/pull/10618) fix(theme): Restore former globalThis.Prism ([@slorber](https://github.com/slorber))
+  - [#10585](https://github.com/facebook/docusaurus/pull/10585) fix(theme): light & dark mode checkbox doesn't announce state switches ([@andrewasche](https://github.com/andrewasche))
+  - [#10439](https://github.com/facebook/docusaurus/pull/10439) fix(theme): upgrade infima, fix footer link width bug ([@slorber](https://github.com/slorber))
+- `docusaurus-faster`
+  - [#10616](https://github.com/facebook/docusaurus/pull/10616) fix(faster): add missing tslib dependency ([@slorber](https://github.com/slorber))
+- `docusaurus`
+  - [#10611](https://github.com/facebook/docusaurus/pull/10611) fix(core): fix DOCUSAURUS_CURRENT_LOCALE = 'undefined' ([@slorber](https://github.com/slorber))
+  - [#10423](https://github.com/facebook/docusaurus/pull/10423) fix(core): always use hash for CSS module class names ([@slorber](https://github.com/slorber))
+- `docusaurus-bundler`, `docusaurus-faster`
+  - [#10605](https://github.com/facebook/docusaurus/pull/10605) fix(core): Use proper swc loader options ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-translations`
+  - [#10551](https://github.com/facebook/docusaurus/pull/10551) fix(translations): complete missing slovenian theme translations ([@patik123](https://github.com/patik123))
+  - [#10507](https://github.com/facebook/docusaurus/pull/10507) fix(theme-translations): add missing Vietnamese translations ([@namnguyenthanhwork](https://github.com/namnguyenthanhwork))
+  - [#10413](https://github.com/facebook/docusaurus/pull/10413) fix(translations): fix Spanish translation for "breadcrumbs" ([@TheMineWay](https://github.com/TheMineWay))
+- `docusaurus-mdx-loader`
+  - [#10553](https://github.com/facebook/docusaurus/pull/10553) fix(mdx-loader): fix cross-compiler cache randomly loading mdx with client/server envs ([@slorber](https://github.com/slorber))
+- `docusaurus-tsconfig`
+  - [#10547](https://github.com/facebook/docusaurus/pull/10547) fix(tsconfig): add `@docusaurus/tsconfig` target es2022 ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-content-blog`
+  - [#10424](https://github.com/facebook/docusaurus/pull/10424) fix(blog): normalize inline authors socials ([@OzakIOne](https://github.com/OzakIOne))
+  - [#10440](https://github.com/facebook/docusaurus/pull/10440) fix(blog): apply baseUrl to relative image in blog authors ([@OzakIOne](https://github.com/OzakIOne))
+- `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-translations`
+  - [#10431](https://github.com/facebook/docusaurus/pull/10431) fix(blog): authors count incorrectly rendered ([@OzakIOne](https://github.com/OzakIOne))
+- `docusaurus-types`, `docusaurus`
+  - [#10420](https://github.com/facebook/docusaurus/pull/10420) fix(types): fix type of PluginModule ([@slorber](https://github.com/slorber))
+
+#### :running_woman: Performance
+
+- `docusaurus-bundler`, `docusaurus-faster`
+  - [#10605](https://github.com/facebook/docusaurus/pull/10605) fix(core): Use proper swc loader options ([@slorber](https://github.com/slorber))
+- Other
+  - [#10601](https://github.com/facebook/docusaurus/pull/10601) perf(ci): Add CI checks to prevent memory, build-time and build-size regressions ([@slorber](https://github.com/slorber))
+- `docusaurus`
+  - [#10599](https://github.com/facebook/docusaurus/pull/10599) fix(core): fix i18n sites SSG memory leak - require.cache ([@slorber](https://github.com/slorber))
+- `docusaurus-mdx-loader`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`
+  - [#10470](https://github.com/facebook/docusaurus/pull/10470) refactor(mdx-loader): re-export metadata module instead of serializing it ([@slorber](https://github.com/slorber))
+  - [#10457](https://github.com/facebook/docusaurus/pull/10457) refactor(mdx-loader): read metadata from memory (loaded content) instead of fs ([@slorber](https://github.com/slorber))
+
+#### :memo: Documentation
+
+- Other
+  - [#10631](https://github.com/facebook/docusaurus/pull/10631) docs: fix frontMatter.mdx.format docs ([@slorber](https://github.com/slorber))
+  - [#10630](https://github.com/facebook/docusaurus/pull/10630) docs: Add missing API ref docs for Docusaurus Faster options ([@slorber](https://github.com/slorber))
+  - [#10592](https://github.com/facebook/docusaurus/pull/10592) docs: resource add docusaurus-i18n ([@moonrailgun](https://github.com/moonrailgun))
+  - [#10535](https://github.com/facebook/docusaurus/pull/10535) docs: add tip about harmless vulnerabilities ([@ilg-ul](https://github.com/ilg-ul))
+  - [#10545](https://github.com/facebook/docusaurus/pull/10545) docs: clarify component naming for markdown import ([@jackrabbit128](https://github.com/jackrabbit128))
+  - [#10416](https://github.com/facebook/docusaurus/pull/10416) docs: corrected typo in search.mdx ([@B0r1sD](https://github.com/B0r1sD))
+  - [#10405](https://github.com/facebook/docusaurus/pull/10405) docs(website): small spellfix on 3.5 update notes ([@Zenahr](https://github.com/Zenahr))
+- `create-docusaurus`
+  - [#10608](https://github.com/facebook/docusaurus/pull/10608) docs: mention config/sidebars run in Node.js runtime ([@slorber](https://github.com/slorber))
+
+#### :robot: Dependencies
+
+- Other
+  - [#10623](https://github.com/facebook/docusaurus/pull/10623) chore(deps): bump actions/setup-node from 4.0.4 to 4.1.0 ([@dependabot[bot]](https://github.com/apps/dependabot))
+  - [#10624](https://github.com/facebook/docusaurus/pull/10624) chore(deps): bump actions/dependency-review-action from 4.3.4 to 4.4.0 ([@dependabot[bot]](https://github.com/apps/dependabot))
+  - [#10539](https://github.com/facebook/docusaurus/pull/10539) chore(deps): bump preactjs/compressed-size-action from 2.6.0 to 2.7.0 ([@dependabot[bot]](https://github.com/apps/dependabot))
+  - [#10530](https://github.com/facebook/docusaurus/pull/10530) chore(deps): bump rollup from 2.79.1 to 2.79.2 ([@dependabot[bot]](https://github.com/apps/dependabot))
+  - [#10518](https://github.com/facebook/docusaurus/pull/10518) chore(deps): bump actions/setup-node from 4.0.2 to 4.0.4 ([@dependabot[bot]](https://github.com/apps/dependabot))
+  - [#10505](https://github.com/facebook/docusaurus/pull/10505) chore(deps): bump dompurify from 3.0.5 to 3.1.6 ([@dependabot[bot]](https://github.com/apps/dependabot))
+  - [#10488](https://github.com/facebook/docusaurus/pull/10488) chore(deps): bump express from 4.19.2 to 4.20.0 ([@dependabot[bot]](https://github.com/apps/dependabot))
+  - [#10449](https://github.com/facebook/docusaurus/pull/10449) chore(deps): bump github/codeql-action from 3.26.3 to 3.26.5 ([@dependabot[bot]](https://github.com/apps/dependabot))
+  - [#10444](https://github.com/facebook/docusaurus/pull/10444) chore(deps): bump micromatch from 4.0.5 to 4.0.8 ([@dependabot[bot]](https://github.com/apps/dependabot))
+  - [#10425](https://github.com/facebook/docusaurus/pull/10425) chore(deps): bump github/codeql-action from 3.26.0 to 3.26.3 ([@dependabot[bot]](https://github.com/apps/dependabot))
+- `docusaurus-plugin-pwa`
+  - [#10455](https://github.com/facebook/docusaurus/pull/10455) chore(deps): bump webpack from 5.88.1 to 5.94.0 ([@dependabot[bot]](https://github.com/apps/dependabot))
+
+#### :wrench: Maintenance
+
+- Other
+  - [#10612](https://github.com/facebook/docusaurus/pull/10612) chore: fix canary version prefix ([@slorber](https://github.com/slorber))
+  - [#10438](https://github.com/facebook/docusaurus/pull/10438) chore(ci): fix setup-node, use LTS by default ([@slorber](https://github.com/slorber))
+  - [#10418](https://github.com/facebook/docusaurus/pull/10418) chore(website): add Rsdoctor plugin ([@slorber](https://github.com/slorber))
+- `docusaurus-babel`, `docusaurus-bundler`, `docusaurus-mdx-loader`, `docusaurus-plugin-debug`, `docusaurus-plugin-pwa`, `docusaurus-plugin-rsdoctor`, `docusaurus-theme-live-codeblock`, `docusaurus`
+  - [#10610](https://github.com/facebook/docusaurus/pull/10610) chore: upgrade minor dependencies ([@slorber](https://github.com/slorber))
+- `docusaurus-bundler`, `docusaurus-faster`
+  - [#10609](https://github.com/facebook/docusaurus/pull/10609) chore: upgrade faster packages ([@slorber](https://github.com/slorber))
+- `docusaurus-bundler`, `docusaurus-logger`, `docusaurus-types`, `docusaurus`
+  - [#10593](https://github.com/facebook/docusaurus/pull/10593) refactor(core): refactor SSG infrastructure ([@slorber](https://github.com/slorber))
+- `docusaurus`
+  - [#10587](https://github.com/facebook/docusaurus/pull/10587) refactor(core): replace serve-handler fork by official deps ([@slorber](https://github.com/slorber))
+  - [#10579](https://github.com/facebook/docusaurus/pull/10579) refactor(core): remove useless Webpack wait plugin ([@slorber](https://github.com/slorber))
+  - [#10485](https://github.com/facebook/docusaurus/pull/10485) refactor(core): rewrite Webpack ChunkAssetPlugin with RuntimeModule ([@slorber](https://github.com/slorber))
+  - [#10448](https://github.com/facebook/docusaurus/pull/10448) refactor(core): Restore null-loader ([@slorber](https://github.com/slorber))
+  - [#10442](https://github.com/facebook/docusaurus/pull/10442) fix(core): use serve-handler fork to remove annoying punycode warning ([@slorber](https://github.com/slorber))
+  - [#10410](https://github.com/facebook/docusaurus/pull/10410) refactor(core): remove useless build forceTerminate exit ([@slorber](https://github.com/slorber))
+- `docusaurus-bundler`, `docusaurus-plugin-pwa`, `docusaurus-types`, `docusaurus`
+  - [#10548](https://github.com/facebook/docusaurus/pull/10548) chore: upgrade Webpack to 5.95 and related deps ([@slorber](https://github.com/slorber))
+- `create-docusaurus`
+  - [#10514](https://github.com/facebook/docusaurus/pull/10514) refactor: remove babel.config.js from init templates + website ([@slorber](https://github.com/slorber))
+- `create-docusaurus`, `docusaurus-babel`, `docusaurus-bundler`, `docusaurus-mdx-loader`, `docusaurus-plugin-pwa`, `docusaurus-theme-classic`, `docusaurus-theme-translations`, `docusaurus-types`, `docusaurus-utils`, `docusaurus`
+  - [#10511](https://github.com/facebook/docusaurus/pull/10511) refactor: create `@docusaurus/bundler` and `@docusaurus/babel` packages ([@slorber](https://github.com/slorber))
+- `create-docusaurus`, `docusaurus-plugin-pwa`, `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-mermaid`, `docusaurus-utils`, `docusaurus`, `eslint-plugin`
+  - [#10509](https://github.com/facebook/docusaurus/pull/10509) chore: Rename Twitter links/labels to X ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-content-docs`, `docusaurus-types`, `docusaurus`
+  - [#10497](https://github.com/facebook/docusaurus/pull/10497) refactor(core): prepare codebase for swappable bundler ([@slorber](https://github.com/slorber))
+- `create-docusaurus`, `docusaurus-utils`
+  - [#10486](https://github.com/facebook/docusaurus/pull/10486) chore: upgrade to TS 5.6 + temporarily use skipLibCheck for TS 5.6 ([@slorber](https://github.com/slorber))
+- `create-docusaurus`, `docusaurus-logger`, `docusaurus-theme-translations`, `docusaurus`
+  - [#10480](https://github.com/facebook/docusaurus/pull/10480) refactor: move PerfLogger from core to @docusaurus/logger ([@slorber](https://github.com/slorber))
+- `docusaurus-remark-plugin-npm2yarn`
+  - [#10454](https://github.com/facebook/docusaurus/pull/10454) chore: upgrade npm-to-yarn to v3 ([@slorber](https://github.com/slorber))
+- `docusaurus-mdx-loader`, `docusaurus-plugin-content-blog`, `docusaurus-plugin-content-docs`, `docusaurus-plugin-content-pages`, `docusaurus`
+  - [#10450](https://github.com/facebook/docusaurus/pull/10450) refactor(mdx-loader): refactor mdx-loader, expose loader creation utils ([@slorber](https://github.com/slorber))
+- `docusaurus-mdx-loader`, `docusaurus-utils`, `docusaurus`
+  - [#10429](https://github.com/facebook/docusaurus/pull/10429) refactor(core): improve handling of server bundle ([@slorber](https://github.com/slorber))
+- `docusaurus-mdx-loader`
+  - [#10422](https://github.com/facebook/docusaurus/pull/10422) refactor(mdx-loader): remove useless usage of mdx loader this.query ([@slorber](https://github.com/slorber))
+
+#### Committers: 19
+
+- Andrew Asche ([@andrewasche](https://github.com/andrewasche))
+- Boris Depoortere ([@B0r1sD](https://github.com/B0r1sD))
+- Chris Cho ([@ccho-mongodb](https://github.com/ccho-mongodb))
+- Flix ([@flixyudh](https://github.com/flixyudh))
+- Joel Campos ([@TheMineWay](https://github.com/TheMineWay))
+- Kamil Moskała ([@moskalakamil](https://github.com/moskalakamil))
+- Kenrick ([@kenrick95](https://github.com/kenrick95))
+- Liviu Ionescu ([@ilg-ul](https://github.com/ilg-ul))
+- Nguyễn Thành Nam ([@namnguyenthanhwork](https://github.com/namnguyenthanhwork))
+- Patrick ([@patik123](https://github.com/patik123))
+- Raghav ([@raghav2005](https://github.com/raghav2005))
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+- Zenahr Barzani ([@Zenahr](https://github.com/Zenahr))
+- [@Olexandr88](https://github.com/Olexandr88)
+- [@Radovenchyk](https://github.com/Radovenchyk)
+- [@jackrabbit128](https://github.com/jackrabbit128)
+- [@k-seltzer](https://github.com/k-seltzer)
+- moonrailgun ([@moonrailgun](https://github.com/moonrailgun))
+- ozaki ([@OzakIOne](https://github.com/OzakIOne))
+
+## 3.5.2 (2024-08-13)
+
+#### :bug: Bug Fix
+
+- `docusaurus-theme-common`
+  - [#10397](https://github.com/facebook/docusaurus/pull/10397) fix(theme-common): restore useContextualSearchFilters public API for retrocompatibility ([@slorber](https://github.com/slorber))
+- `docusaurus`
+  - [#10391](https://github.com/facebook/docusaurus/pull/10391) fix(core): always alias React/ReactDOM to site dependency so that importing MDX from anywhere works ([@slorber](https://github.com/slorber))
+- `create-docusaurus`, `docusaurus-plugin-content-blog`
+  - [#10392](https://github.com/facebook/docusaurus/pull/10392) fix(create-docusaurus): Improve init templates blog setup + fix warnings ([@slorber](https://github.com/slorber))
+- `docusaurus-theme-classic`
+  - [#10390](https://github.com/facebook/docusaurus/pull/10390) fix(theme): Adjust blog authors line height to show descenders in lowercase letters (`g`, `j`, `p`, `q`, and `y`) ([@josh-wong](https://github.com/josh-wong))
+
+#### :nail_care: Polish
+
+- `docusaurus-theme-classic`, `docusaurus-theme-common`, `docusaurus-theme-translations`
+  - [#10394](https://github.com/facebook/docusaurus/pull/10394) fix(translations): change casing of some en labels ([@cstangerup](https://github.com/cstangerup))
+
+#### :memo: Documentation
+
+- [#10393](https://github.com/facebook/docusaurus/pull/10393) docs(showcase): remove sites not using Docusaurus anymore ([@GatienBoquet](https://github.com/GatienBoquet))
+
+#### :robot: Dependencies
+
+- [#10396](https://github.com/facebook/docusaurus/pull/10396) chore(deps): bump github/codeql-action from 3.25.13 to 3.26.0 ([@dependabot[bot]](https://github.com/apps/dependabot))
+
+#### Committers: 4
+
+- Christian Stangerup ([@cstangerup](https://github.com/cstangerup))
+- Gatien Boquet ([@GatienBoquet](https://github.com/GatienBoquet))
+- Josh Wong ([@josh-wong](https://github.com/josh-wong))
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+
 ## 3.5.1 (2024-08-09)
 
 #### :bug: Bug Fix

CODE_OF_CONDUCT.md

@@ -1,3 +1,3 @@
 # Code of Conduct
 
-Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please [read the full text](https://code.fb.com/codeofconduct/) so that you can understand what actions will and will not be tolerated.
+Meta has adopted a Code of Conduct that we expect project participants to adhere to. Please [read the full text](https://code.fb.com/codeofconduct/) so that you can understand what actions will and will not be tolerated.

CONTRIBUTING.md

@@ -9,7 +9,7 @@ The [Open Source Guides](https://opensource.guide/) website has a collection of
 
 ## Code of Conduct
 
-Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](https://code.fb.com/codeofconduct) so that you can understand what actions will and will not be tolerated.
+Meta has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](https://code.fb.com/codeofconduct) so that you can understand what actions will and will not be tolerated.
 
 ## Get Involved
 
@@ -21,7 +21,7 @@ There are many ways to contribute to Docusaurus, and many of them do not involve
 - Read through the [Docusaurus docs](https://docusaurus.io/docs/installation). If you find anything that is confusing or can be improved, you can click "Edit this page" at the bottom of most docs, which takes you to the GitHub interface to make and propose changes.
 - Take a look at the [features requested](https://github.com/facebook/docusaurus/labels/feature) by others in the community and consider opening a pull request if you see something you want to work on.
 
-Contributions are very welcome. If you think you need help planning your contribution, please ping us on Twitter at [@docusaurus](https://twitter.com/docusaurus) and let us know you are looking for a bit of help.
+Contributions are very welcome. If you think you need help planning your contribution, please ping us on X at [@docusaurus](https://x.com/docusaurus) and let us know you are looking for a bit of help.
 
 ### Join our Discord Channel
 
@@ -63,7 +63,7 @@ If you're only fixing a bug, it's fine to submit a pull request right away but w
 
 ### Security Bugs
 
-Facebook has a [bounty program](https://www.facebook.com/whitehat/) for the safe disclosure of security bugs. With that in mind, please do not file public issues; go through the process outlined on that page.
+Meta has a [bounty program](https://www.facebook.com/whitehat/) for the safe disclosure of security bugs. With that in mind, please do not file public issues; go through the process outlined on that page.
 
 ### Feature requests
 
@@ -206,7 +206,7 @@ This is also auto-fixable with the `header/header` ESLint rule.
 
 ### Contributor License Agreement (CLA)
 
-In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you've done this for another Facebook open source project, you're good to go. If you are submitting a pull request for the first time, the Facebook GitHub Bot will reply with a link to the CLA form. You may also [complete your CLA here](https://code.facebook.com/cla).
+In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you've done this for another Meta open source project, you're good to go. If you are submitting a pull request for the first time, the Meta GitHub Bot will reply with a link to the CLA form. You may also [complete your CLA here](https://code.facebook.com/cla).
 
 After you have signed the CLA, the CLA bot would automatically update the PR status. There's no need to open a new PR.
 

README.md

@@ -10,7 +10,7 @@
 </div>
 
 <p align="center">
-  <a href="https://twitter.com/docusaurus"><img src="https://img.shields.io/twitter/follow/docusaurus.svg?style=social" align="right" alt="Twitter Follow" /></a>
+  <a href="https://x.com/docusaurus"><img src="https://img.shields.io/twitter/follow/docusaurus.svg?style=social" align="right" alt="Twitter Follow" /></a>
   <a href="#backers" alt="sponsors on Open Collective"><img src="https://opencollective.com/Docusaurus/backers/badge.svg" /></a>
   <a href="#sponsors" alt="Sponsors on Open Collective"><img src="https://opencollective.com/Docusaurus/sponsors/badge.svg" /></a>
   <a href="https://www.npmjs.com/package/@docusaurus/core"><img src="https://img.shields.io/npm/v/@docusaurus/core.svg?style=flat" alt="npm version"></a>
@@ -59,11 +59,11 @@ npm init docusaurus@latest
 
 ## Contributing
 
-We've released Docusaurus because it helps us better scale and supports the many OSS projects at Facebook. We hope that other organizations can benefit from the project. We are thankful for any contributions from the community.
+We've released Docusaurus because it helps us better scale and supports the many OSS projects at Meta. We hope that other organizations can benefit from the project. We are thankful for any contributions from the community.
 
 ### [Code of Conduct](https://code.fb.com/codeofconduct)
 
-Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](https://code.fb.com/codeofconduct) so that you can understand what actions will and will not be tolerated.
+Meta has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](https://code.fb.com/codeofconduct) so that you can understand what actions will and will not be tolerated.
 
 ### Contributing guide
 
@@ -80,7 +80,7 @@ We have a few channels for contact:
 - [Discord](https://discord.gg/docusaurus):
   - `#general` for those using Docusaurus.
   - `#contributors` for those wanting to contribute to the Docusaurus core.
-- [@docusaurus](https://twitter.com/docusaurus) on Twitter
+- [@docusaurus](https://x.com/docusaurus) X
 - [GitHub Issues](https://github.com/facebook/docusaurus/issues)
 
 ## Contributors

admin/new.docusaurus.io/package.json

@@ -1,6 +1,6 @@
 {
   "name": "new.docusaurus.io",
-  "version": "3.5.1",
+  "version": "3.7.0",
   "private": true,
   "scripts": {
     "start": "npx --package netlify-cli netlify dev"

admin/publish.md

@@ -218,7 +218,7 @@ Create a separate branch/PR and run `yarn examples:generate`
 
 ### 9. Notify people about new release (optional but desirable)
 
-After new release, it is cool to notify our users about this in the Discord chat (`#announcements` channel) and write summaries on Twitter using the following templates.
+After new release, it is cool to notify our users about this in the Discord chat (`#announcements` channel) and write summaries on X using the following templates.
 
 For Discord:
 
@@ -227,7 +227,7 @@ A new version %VER% is available now! 🎉
 See release notes at the following link https://github.com/facebook/docusaurus/releases/tag/%VER%
 ```
 
-For Twitter:
+For X:
 
 ```
 💥 A new version %VER% is available now! 💥

admin/scripts/formatLighthouseReport.js

@@ -41,16 +41,23 @@ function createURL(url) {
  * @param {Object} param0
  * @param {string} param0.url
  * @param {LighthouseSummary} param0.summary
- * @param {string} param0.reportUrl
+ * @param {string | undefined} param0.reportUrl
+ * @return {string}
  */
-const createMarkdownTableRow = ({url, summary, reportUrl}) =>
-  [
-    `| [${createURL(url).pathname}](${url})`,
+const createMarkdownTableRow = ({url, summary, reportUrl}) => {
+  const columns = [
+    `[${createURL(url).pathname}](${url})`,
+
     .../** @type {(keyof LighthouseSummary)[]} */ (
       Object.keys(summaryKeys)
     ).map((k) => scoreEntry(summary[k])),
-    `[Report](${reportUrl}) |`,
-  ].join(' | ');
+
+    // See https://github.com/facebook/docusaurus/pull/10527
+    reportUrl ? `[Report](${reportUrl})` : `Report N/A`,
+  ];
+
+  return `| ${columns.join(' | ')} |`;
+};
 
 const createMarkdownTableHeader = () => [
   ['| URL', ...Object.values(summaryKeys), 'Report |'].join(' | '),
@@ -64,18 +71,15 @@ const createMarkdownTableHeader = () => [
  * @param {Record<string, string>} param0.links
  * @param {{url: string, summary: LighthouseSummary}[]} param0.results
  */
-const createLighthouseReport = ({results, links}) => {
+export default function formatLighthouseReport({results, links}) {
   const tableHeader = createMarkdownTableHeader();
   const tableBody = results.map((result) => {
-    const testUrl = /** @type {string} */ (
-      Object.keys(links).find((key) => key === result.url)
-    );
-    const reportPublicUrl = /** @type {string} */ (links[testUrl]);
-
+    const {url, summary} = result;
+    const reportUrl = /** @type {string | undefined} */ (links[result.url]);
     return createMarkdownTableRow({
-      url: testUrl,
-      summary: result.summary,
-      reportUrl: reportPublicUrl,
+      url,
+      summary,
+      reportUrl,
     });
   });
   const comment = [
@@ -86,6 +90,4 @@ const createLighthouseReport = ({results, links}) => {
     '',
   ];
   return comment.join('\n');
-};
-
-export default createLighthouseReport;
+}

admin/scripts/resizeImage.js

@@ -9,9 +9,9 @@ import fs from 'fs-extra';
 import path from 'path';
 import {fileURLToPath} from 'url';
 import {program} from 'commander';
-import logger from '@docusaurus/logger';
+import {logger} from '@docusaurus/logger';
 import sharp from 'sharp';
-import imageSize from 'image-size';
+import {imageSizeFromFile} from 'image-size/fromFile';
 
 // You can use it as:
 //
@@ -64,7 +64,7 @@ program
 
     await Promise.all(
       images.map(async (imgPath) => {
-        const {width, height} = imageSize(imgPath);
+        const {width, height} = await imageSizeFromFile(imgPath);
         const targetWidth =
           options.width ?? (imgPath.includes(showcasePath) ? 640 : 1000);
         const targetHeight =

admin/scripts/test-release.sh

@@ -5,7 +5,9 @@
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 
-set -euo pipefail
+set -xeuo pipefail
+
+rm -rf ../test-website
 
 CUSTOM_REGISTRY_URL="http://localhost:4873"
 NEW_VERSION="$(node -p "require('./packages/docusaurus/package.json').version")-NEW"
@@ -52,7 +54,8 @@ git diff --name-only -- '*.json' | sed 's, ,\\&,g' | xargs git checkout --
 cd ..
 
 # Build skeleton website with new version
-npm_config_registry="$CUSTOM_REGISTRY_URL" npx create-docusaurus@"$NEW_VERSION" test-website classic --javascript $EXTRA_OPTS
+npm_config_registry="$CUSTOM_REGISTRY_URL" npx --yes --loglevel silly create-docusaurus@"$NEW_VERSION" test-website classic --javascript $EXTRA_OPTS
+
 
 # Stop Docker container
 if [[ -z "${KEEP_CONTAINER:-true}" ]] && ( $(docker container inspect "$CONTAINER_NAME" > /dev/null 2>&1) ); then

admin/test-bad-package/README.mdx

@@ -12,7 +12,7 @@ import {version as ReactVersion} from 'react';
 import {version as ReactDOMVersion} from 'react-dom';
 
 export function TestComponent() {
-  const expectedVersion = 18;
+  const expectedVersion = 19;
   if (!ReactVersion.startsWith(`${expectedVersion}`)) {
     throw new Error(
       `'test-bad-package/README.mdx' is rendered with bad React version: ${ReactVersion}`,

admin/test-bad-package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "test-bad-package",
-  "version": "3.5.1",
+  "version": "3.7.0",
   "private": true,
   "dependencies": {
+    "@mdx-js/react": "1.0.1",
     "react": "16.14.0",
-    "react-dom": "16.14.0",
-    "@mdx-js/react": "1.0.1"
+    "react-dom": "16.14.0"
   }
 }

argos/package.json

@@ -1,17 +1,17 @@
 {
   "name": "argos",
-  "version": "3.5.1",
+  "version": "3.7.0",
   "description": "Argos visual diff tests",
   "license": "MIT",
   "private": true,
   "scripts": {
     "screenshot": "playwright test",
-    "upload": "npx @argos-ci/cli upload ./screenshots",
+    "upload": "npx @argos-ci/cli upload ./screenshots/chromium",
     "report": "playwright show-report"
   },
   "dependencies": {
-    "@argos-ci/playwright": "^1.9.3",
-    "@playwright/test": "^1.41.2",
-    "cheerio": "^1.0.0-rc.12"
+    "@argos-ci/playwright": "^2.0.0",
+    "@playwright/test": "^1.48.1",
+    "cheerio": "1.0.0-rc.12"
   }
 }

argos/tests/screenshot.spec.ts

@@ -45,6 +45,24 @@ function isBlacklisted(pathname: string) {
     '/showcase',
     // Long blog post with many image carousels, often timeouts
     '/blog/2022/08/01/announcing-docusaurus-2.0',
+
+    // DOGFOOD TESTS
+    // React key errors:
+    '/tests/docs/tests/toc-partials',
+    // Console errors
+    '/tests/pages/diagrams',
+    '/tests/pages/markdown-tests-md',
+    '/tests/pages/react-18',
+    // Flaky because of hydration error
+    '/tests/blog/archive',
+    '/tests/pages/code-block-tests',
+    '/tests/pages/embeds',
+    // Flaky because of hydration error with docusaurus serve + .html
+    '/tests/blog/x/y/z.html',
+    '/tests/docs/dummy.html',
+    // Cause weird docusaurus serve errors:
+    '/tests/docs/tests/ascii/%C3%A6%C3%B8%C3%A5',
+    '/tests/docs/tests/ascii/folder/%C3%A6%C3%B8%C3%A5',
   ];
 
   return (
@@ -52,6 +70,13 @@ function isBlacklisted(pathname: string) {
     pathname.startsWith('/changelog') ||
     // versioned docs
     pathname.match(/^\/docs\/((\d\.\d\.\d)|(next))\//) ||
+    // verbose useless dogfooding pages
+    pathname.startsWith('/tests/docs/toc/') ||
+    pathname.startsWith('/tests/docs/tags/') ||
+    pathname.startsWith('/tests/docs/tests/category-links') ||
+    pathname.startsWith('/tests/docs/tests/visibility') ||
+    pathname.startsWith('/tests/blog/page/') ||
+    pathname.startsWith('/tests/blog/tags/') ||
     // manually excluded urls
     BlacklistedPathnames.includes(pathname)
   );
@@ -105,28 +130,26 @@ function throwOnConsole(page: Page) {
   const typesToCheck = ['error', 'warning'];
 
   const ignoreMessages = [
-    // This mismatch warning looks like a React 18 bug to me
-    'Warning: Prop `%s` did not match. Server: %s Client: %s%s className "null" ""',
-
     // TODO this fetch error message is unexpected and should be fixed
     //  it's already happening in main branch
     'Failed to load resource: the server responded with a status of 404 (Not Found)',
 
-    // TODO looks like a legit hydration bug to fix
-    // on /blog/releases/2.4
-    'Warning: Prop `%s` did not match. Server: %s Client: %s%s href "/docs" "/docs?docusaurus-theme=light"',
-    'Warning: Prop `%s` did not match. Server: %s Client: %s%s href "/docs" "/docs?docusaurus-theme=dark"',
-    // on /blog/releases/3.0
-    'Warning: Prop `%s` did not match. Server: %s Client: %s%s href "/docs" "/docs?docusaurus-data-navbar=false&docusaurus-data-red-border"',
-    // on /docs/styling-layout
-    'Warning: Prop `%s` did not match. Server: %s Client: %s%s href "/docs" "/docs?docusaurus-data-navbar=false&docusaurus-data-red-border"',
-    'Warning: Prop `%s` did not match. Server: %s Client: %s%s href "/docs/configuration" "/docs/configuration?docusaurus-theme=light"',
-    'Warning: Prop `%s` did not match. Server: %s Client: %s%s href "/docs/configuration" "/docs/configuration?docusaurus-theme=dark"',
+    // TODO legit hydration bugs to fix on embeds of /docs/styling-layout
+    //  useLocation() returns window.search/hash immediately :s
+    '/docs/configuration?docusaurus-theme=light',
+    '/docs/configuration?docusaurus-theme=dark',
+
+    // Warning because react-live not supporting React automatic JSX runtime
+    // See https://github.com/FormidableLabs/react-live/issues/405
+    'Your app (or one of its dependencies) is using an outdated JSX transform. Update to the modern JSX transform for faster performance',
 
     // TODO weird problem related to KaTeX fonts refusing to decode?
     //  on /docs/markdown-features/math-equations
     'Failed to decode downloaded font: http://localhost:3000/katex/fonts/',
     'OTS parsing error: Failed to convert WOFF 2.0 font to SFNT',
+
+    // Mermaid warning, see https://github.com/mermaid-js/mermaid/issues/6031
+    'Do not assign mappings to elements without corresponding data',
   ];
 
   page.on('console', (message) => {

examples/README.md

@@ -2,7 +2,7 @@
 
 These example projects are generated with the init CLI:
 
-```
+```bash
 npx @docusaurus/init@latest init examples/<templateName> <templateName>`
 ```
 

examples/classic-typescript/README.md

@@ -4,13 +4,13 @@ This website is built using [Docusaurus](https://docusaurus.io/), a modern stati
 
 ### Installation
 
-```
+```bash
 $ yarn
 ```
 
 ### Local Development
 
-```
+```bash
 $ yarn start
 ```
 
@@ -18,7 +18,7 @@ This command starts a local development server and opens up a browser window. Mo
 
 ### Build
 
-```
+```bash
 $ yarn build
 ```
 
@@ -28,13 +28,13 @@ This command generates static content into the `build` directory and can be serv
 
 Using SSH:
 
-```
+```bash
 $ USE_SSH=true yarn deploy
 ```
 
 Not using SSH:
 
-```
+```bash
 $ GIT_USER=<Your GitHub username> yarn deploy
 ```
 

examples/classic-typescript/babel.config.js

@@ -1,3 +0,0 @@
-module.exports = {
-  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
-};

examples/classic-typescript/blog/2019-05-28-first-blog-post.md

@@ -1,12 +1,12 @@
 ---
 slug: first-blog-post
 title: First Blog Post
-authors:
-  name: Gao Wei
-  title: Docusaurus Core Team
-  url: https://github.com/wgao19
-  image_url: https://github.com/wgao19.png
+authors: [slorber, yangshun]
 tags: [hola, docusaurus]
 ---
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+Lorem ipsum dolor sit amet...
+
+<!-- truncate -->
+
+...consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

examples/classic-typescript/blog/2019-05-29-long-blog-post.md

@@ -1,7 +1,7 @@
 ---
 slug: long-blog-post
 title: Long Blog Post
-authors: endi
+authors: yangshun
 tags: [hello, docusaurus]
 ---
 
@@ -9,7 +9,7 @@ This is the summary of a very long blog post,
 
 Use a `<!--` `truncate` `-->` comment to limit blog post size in the list view.
 
-<!--truncate-->
+<!-- truncate -->
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
 

examples/classic-typescript/blog/2021-08-01-mdx-blog-post.mdx

@@ -11,10 +11,14 @@ Blog posts support [Docusaurus Markdown features](https://docusaurus.io/docs/mar
 
 Use the power of React to create interactive blog posts.
 
+:::
+
+{/* truncate */}
+
+For example, use JSX to create an interactive button:
+
 ```js
 <button onClick={() => alert('button clicked!')}>Click me!</button>
 ```
 
 <button onClick={() => alert('button clicked!')}>Click me!</button>
-
-:::

examples/classic-typescript/blog/2021-08-26-welcome/index.md

@@ -7,6 +7,10 @@ tags: [facebook, hello, docusaurus]
 
 [Docusaurus blogging features](https://docusaurus.io/docs/blog) are powered by the [blog plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog).
 
+Here are a few tips you might find useful.
+
+<!-- truncate -->
+
 Simply add Markdown files (or folders) to the `blog` directory.
 
 Regular blog authors can be added to `authors.yml`.

examples/classic-typescript/blog/authors.yml

@@ -1,14 +1,9 @@
-endi:
-  name: Endilie Yacop Sucipto
-  title: Maintainer of Docusaurus
-  url: https://github.com/endiliey
-  image_url: https://github.com/endiliey.png
-
 yangshun:
   name: Yangshun Tay
   title: Front End Engineer @ Facebook
   url: https://github.com/yangshun
   image_url: https://github.com/yangshun.png
+  page: true
   socials:
     x: yangshunz
     github: yangshun
@@ -18,6 +13,9 @@ slorber:
   title: Docusaurus maintainer
   url: https://sebastienlorber.com
   image_url: https://github.com/slorber.png
+  page:
+    # customize the url of the author page at /blog/authors/<permalink>
+    permalink: '/all-sebastien-lorber-articles'
   socials:
     x: sebastienlorber
     linkedin: sebastienlorber

examples/classic-typescript/blog/tags.yml

@@ -2,14 +2,17 @@ facebook:
   label: Facebook
   permalink: /facebook
   description: Facebook tag description
+
 hello:
   label: Hello
   permalink: /hello
   description: Hello tag description
+
 docusaurus:
   label: Docusaurus
   permalink: /docusaurus
   description: Docusaurus tag description
+
 hola:
   label: Hola
   permalink: /hola

examples/classic-typescript/docusaurus.config.ts

@@ -2,6 +2,8 @@ import {themes as prismThemes} from 'prism-react-renderer';
 import type {Config} from '@docusaurus/types';
 import type * as Preset from '@docusaurus/preset-classic';
 
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
 const config: Config = {
   title: 'My Site',
   tagline: 'Dinosaurs are cool',
@@ -50,6 +52,10 @@ const config: Config = {
           // Remove this to remove the "edit this page" links.
           editUrl:
             'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
+          // Useful options to enforce blogging best practices
+          onInlineTags: 'warn',
+          onInlineAuthors: 'warn',
+          onUntruncatedBlogPosts: 'warn',
         },
         theme: {
           customCss: './src/css/custom.css',
@@ -106,8 +112,8 @@ const config: Config = {
               href: 'https://discordapp.com/invite/docusaurus',
             },
             {
-              label: 'Twitter',
-              href: 'https://twitter.com/docusaurus',
+              label: 'X',
+              href: 'https://x.com/docusaurus',
             },
           ],
         },

examples/classic-typescript/package.json

@@ -16,19 +16,19 @@
     "dev": "docusaurus start"
   },
   "dependencies": {
-    "@docusaurus/core": "3.5.1",
-    "@docusaurus/preset-classic": "3.5.1",
+    "@docusaurus/core": "3.7.0",
+    "@docusaurus/preset-classic": "3.7.0",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.5.1",
-    "@docusaurus/tsconfig": "3.5.1",
-    "@docusaurus/types": "3.5.1",
-    "typescript": "~5.5.2"
+    "@docusaurus/module-type-aliases": "3.7.0",
+    "@docusaurus/tsconfig": "3.7.0",
+    "@docusaurus/types": "3.7.0",
+    "typescript": "~5.6.2"
   },
   "browserslist": {
     "production": [

examples/classic-typescript/sidebars.ts

@@ -1,5 +1,7 @@
 import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
 
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
 /**
  * Creating a sidebar enables you to:
  - create an ordered group of docs

examples/classic-typescript/src/components/HomepageFeatures/index.tsx

@@ -1,3 +1,4 @@
+import type {ReactNode} from 'react';
 import clsx from 'clsx';
 import Heading from '@theme/Heading';
 import styles from './styles.module.css';
@@ -5,7 +6,7 @@ import styles from './styles.module.css';
 type FeatureItem = {
   title: string;
   Svg: React.ComponentType<React.ComponentProps<'svg'>>;
-  description: JSX.Element;
+  description: ReactNode;
 };
 
 const FeatureList: FeatureItem[] = [
@@ -55,7 +56,7 @@ function Feature({title, Svg, description}: FeatureItem) {
   );
 }
 
-export default function HomepageFeatures(): JSX.Element {
+export default function HomepageFeatures(): ReactNode {
   return (
     <section className={styles.features}>
       <div className="container">

examples/classic-typescript/src/pages/index.tsx

@@ -1,3 +1,4 @@
+import type {ReactNode} from 'react';
 import clsx from 'clsx';
 import Link from '@docusaurus/Link';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
@@ -28,7 +29,7 @@ function HomepageHeader() {
   );
 }
 
-export default function Home(): JSX.Element {
+export default function Home(): ReactNode {
   const {siteConfig} = useDocusaurusContext();
   return (
     <Layout

examples/classic-typescript/tsconfig.json

@@ -3,5 +3,6 @@
   "extends": "@docusaurus/tsconfig",
   "compilerOptions": {
     "baseUrl": "."
-  }
+  },
+  "exclude": [".docusaurus", "build"]
 }

examples/classic/README.md

@@ -4,13 +4,13 @@ This website is built using [Docusaurus](https://docusaurus.io/), a modern stati
 
 ### Installation
 
-```
+```bash
 $ yarn
 ```
 
 ### Local Development
 
-```
+```bash
 $ yarn start
 ```
 
@@ -18,7 +18,7 @@ This command starts a local development server and opens up a browser window. Mo
 
 ### Build
 
-```
+```bash
 $ yarn build
 ```
 
@@ -28,13 +28,13 @@ This command generates static content into the `build` directory and can be serv
 
 Using SSH:
 
-```
+```bash
 $ USE_SSH=true yarn deploy
 ```
 
 Not using SSH:
 
-```
+```bash
 $ GIT_USER=<Your GitHub username> yarn deploy
 ```
 

examples/classic/babel.config.js

@@ -1,3 +0,0 @@
-module.exports = {
-  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
-};

examples/classic/blog/2019-05-28-first-blog-post.md

@@ -1,12 +1,12 @@
 ---
 slug: first-blog-post
 title: First Blog Post
-authors:
-  name: Gao Wei
-  title: Docusaurus Core Team
-  url: https://github.com/wgao19
-  image_url: https://github.com/wgao19.png
+authors: [slorber, yangshun]
 tags: [hola, docusaurus]
 ---
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+Lorem ipsum dolor sit amet...
+
+<!-- truncate -->
+
+...consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

examples/classic/blog/2019-05-29-long-blog-post.md

@@ -1,7 +1,7 @@
 ---
 slug: long-blog-post
 title: Long Blog Post
-authors: endi
+authors: yangshun
 tags: [hello, docusaurus]
 ---
 
@@ -9,7 +9,7 @@ This is the summary of a very long blog post,
 
 Use a `<!--` `truncate` `-->` comment to limit blog post size in the list view.
 
-<!--truncate-->
+<!-- truncate -->
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
 

examples/classic/blog/2021-08-01-mdx-blog-post.mdx

@@ -11,10 +11,14 @@ Blog posts support [Docusaurus Markdown features](https://docusaurus.io/docs/mar
 
 Use the power of React to create interactive blog posts.
 
+:::
+
+{/* truncate */}
+
+For example, use JSX to create an interactive button:
+
 ```js
 <button onClick={() => alert('button clicked!')}>Click me!</button>
 ```
 
 <button onClick={() => alert('button clicked!')}>Click me!</button>
-
-:::

examples/classic/blog/2021-08-26-welcome/index.md

@@ -7,6 +7,10 @@ tags: [facebook, hello, docusaurus]
 
 [Docusaurus blogging features](https://docusaurus.io/docs/blog) are powered by the [blog plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog).
 
+Here are a few tips you might find useful.
+
+<!-- truncate -->
+
 Simply add Markdown files (or folders) to the `blog` directory.
 
 Regular blog authors can be added to `authors.yml`.

examples/classic/blog/authors.yml

@@ -1,14 +1,9 @@
-endi:
-  name: Endilie Yacop Sucipto
-  title: Maintainer of Docusaurus
-  url: https://github.com/endiliey
-  image_url: https://github.com/endiliey.png
-
 yangshun:
   name: Yangshun Tay
   title: Front End Engineer @ Facebook
   url: https://github.com/yangshun
   image_url: https://github.com/yangshun.png
+  page: true
   socials:
     x: yangshunz
     github: yangshun
@@ -18,6 +13,9 @@ slorber:
   title: Docusaurus maintainer
   url: https://sebastienlorber.com
   image_url: https://github.com/slorber.png
+  page:
+    # customize the url of the author page at /blog/authors/<permalink>
+    permalink: '/all-sebastien-lorber-articles'
   socials:
     x: sebastienlorber
     linkedin: sebastienlorber

examples/classic/blog/tags.yml

@@ -2,14 +2,17 @@ facebook:
   label: Facebook
   permalink: /facebook
   description: Facebook tag description
+
 hello:
   label: Hello
   permalink: /hello
   description: Hello tag description
+
 docusaurus:
   label: Docusaurus
   permalink: /docusaurus
   description: Docusaurus tag description
+
 hola:
   label: Hola
   permalink: /hola

examples/classic/docusaurus.config.js

@@ -6,6 +6,8 @@
 
 import {themes as prismThemes} from 'prism-react-renderer';
 
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
 /** @type {import('@docusaurus/types').Config} */
 const config = {
   title: 'My Site',
@@ -56,6 +58,10 @@ const config = {
           // Remove this to remove the "edit this page" links.
           editUrl:
             'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
+          // Useful options to enforce blogging best practices
+          onInlineTags: 'warn',
+          onInlineAuthors: 'warn',
+          onUntruncatedBlogPosts: 'warn',
         },
         theme: {
           customCss: './src/css/custom.css',
@@ -114,8 +120,8 @@ const config = {
                 href: 'https://discordapp.com/invite/docusaurus',
               },
               {
-                label: 'Twitter',
-                href: 'https://twitter.com/docusaurus',
+                label: 'X',
+                href: 'https://x.com/docusaurus',
               },
             ],
           },

examples/classic/package.json

@@ -15,17 +15,17 @@
     "dev": "docusaurus start"
   },
   "dependencies": {
-    "@docusaurus/core": "3.5.1",
-    "@docusaurus/preset-classic": "3.5.1",
+    "@docusaurus/core": "3.7.0",
+    "@docusaurus/preset-classic": "3.7.0",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.5.1",
-    "@docusaurus/types": "3.5.1"
+    "@docusaurus/module-type-aliases": "3.7.0",
+    "@docusaurus/types": "3.7.0"
   },
   "browserslist": {
     "production": [

examples/classic/sidebars.js

@@ -1,3 +1,7 @@
+// @ts-check
+
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
 /**
  * Creating a sidebar enables you to:
  - create an ordered group of docs
@@ -7,11 +11,9 @@
  The sidebars can be generated from the filesystem, or explicitly defined here.
 
  Create as many sidebars as you want.
+
+ @type {import('@docusaurus/plugin-content-docs').SidebarsConfig}
  */
-
-// @ts-check
-
-/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
   tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],

lerna.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.5.1",
+  "version": "3.7.0",
   "npmClient": "yarn",
   "useWorkspaces": true,
   "useNx": false,
@@ -13,7 +13,8 @@
       "pr: polish": ":nail_care: Polish",
       "pr: documentation": ":memo: Documentation",
       "pr: dependencies": ":robot: Dependencies",
-      "pr: maintenance": ":wrench: Maintenance"
+      "pr: maintenance": ":wrench: Maintenance",
+      "pr: translations": ":globe_with_meridians: Translations"
     },
     "cacheDir": ".changelog"
   }

package.json

@@ -15,6 +15,7 @@
   "scripts": {
     "start": "yarn build:packages && yarn start:website",
     "start:website": "yarn workspace website start",
+    "start:website:profile": "DOCUSAURUS_BUNDLER_CPU_PROFILE=true DOCUSAURUS_RSPACK_TRACE=true yarn workspace website start",
     "start:website:baseUrl": "yarn workspace website start:baseUrl",
     "start:website:blogOnly": "yarn workspace website start:blogOnly",
     "start:website:deployPreview": "cross-env NETLIFY=true CONTEXT='deploy-preview' yarn workspace website start",
@@ -22,12 +23,15 @@
     "build": "yarn build:packages && yarn build:website",
     "build:packages": "lerna run build --no-private",
     "build:website": "yarn workspace website build",
+    "build:website:profile": "DOCUSAURUS_BUNDLER_CPU_PROFILE=true DOCUSAURUS_RSPACK_TRACE=true yarn workspace website build",
     "build:website:baseUrl": "yarn workspace website build:baseUrl",
     "build:website:blogOnly": "yarn workspace website build:blogOnly",
     "build:website:deployPreview:testWrap": "yarn workspace website test:swizzle:wrap:ts",
     "build:website:deployPreview:build": "cross-env NETLIFY=true CONTEXT='deploy-preview' yarn workspace website build",
     "build:website:deployPreview": "yarn build:website:deployPreview:testWrap && yarn build:website:deployPreview:build",
     "build:website:fast": "yarn workspace website build:fast",
+    "build:website:fast:rsdoctor": "yarn workspace website build:fast:rsdoctor",
+    "build:website:fast:profile": "yarn workspace website build:fast:profile",
     "build:website:en": "yarn workspace website build --locale en",
     "clear:website": "yarn workspace website clear",
     "serve:website": "yarn workspace website serve",
@@ -39,13 +43,16 @@
     "crowdin:upload:website": "crowdin upload sources --config ./crowdin-v2.yaml",
     "crowdin:download": "crowdin download --config ./crowdin-v2.yaml",
     "crowdin:download:website": "yarn crowdin:download --language fr --language ko --language pt-BR --language zh-CN --language ja",
+    "argos": "yarn argos:build && yarn argos:screenshot",
+    "argos:build": "cross-env DOCUSAURUS_ARGOS_BUILD=true yarn build:website:fast --dev",
     "argos:screenshot": "yarn workspace argos screenshot",
     "canary": "yarn canary:bumpVersion && yarn canary:publish",
-    "canary:version": "echo 0.0.0-`git rev-list --count HEAD`+`git rev-parse --short HEAD`",
+    "canary:getCoreVersion": "node -p \"require('./packages/docusaurus/package.json').version\"",
+    "canary:version": "echo `yarn --silent canary:getCoreVersion`-canary-`git rev-list --count HEAD`+`git rev-parse --short HEAD`",
     "canary:bumpVersion": "yarn lerna version `yarn --silent canary:version` --exact --no-push --yes",
     "canary:publish": "yarn lerna publish from-package --dist-tag canary --yes --no-verify-access",
     "changelog": "lerna-changelog",
-    "postinstall": "yarn lock:update && yarn build:packages",
+    "postinstall": "patch-package && yarn lock:update && yarn build:packages",
     "prepare": "husky install",
     "format": "prettier --write .",
     "format:diff": "prettier --list-different .",
@@ -54,7 +61,7 @@
     "lint:js": "eslint --cache --report-unused-disable-directives \"**/*.{js,jsx,ts,tsx,mjs}\"",
     "lint:js:fix": "yarn lint:js --fix",
     "lint:spelling": "cspell \"**\" --no-progress --show-context --show-suggestions",
-    "lint:spelling:fix": "yarn rimraf project-words.txt && echo \"# Project Words - DO NOT TOUCH - This is updated through CI\" >> project-words.txt && yarn -s lint:spelling --words-only --unique --no-exit-code --no-summary \"**\" | cross-env LC_ALL=en_US.UTF-8 sort --ignore-case >> project-words.txt",
+    "lint:spelling:fix": "yarn rimraf project-words.txt && echo \"# Project Words - DO NOT TOUCH - This is updated through CI\" >> project-words.txt && yarn -s lint:spelling --words-only --unique --no-exit-code --no-summary \"**\" | cross-env LC_ALL=C sort --ignore-case >> project-words.txt",
     "lint:style": "stylelint \"**/*.css\"",
     "lint:style:fix": "yarn lint:style --fix",
     "lerna": "lerna",
@@ -69,23 +76,22 @@
   "devDependencies": {
     "@crowdin/cli": "^3.13.0",
     "@prettier/plugin-xml": "^2.2.0",
-    "@swc/core": "1.2.197",
-    "@swc/jest": "^0.2.26",
+    "@swc/core": "^1.7.14",
+    "@swc/jest": "^0.2.36",
     "@testing-library/react-hooks": "^8.0.1",
     "@types/fs-extra": "^9.0.13",
-    "@types/jest": "^29.5.3",
+    "@types/jest": "^29.5.12",
     "@types/lodash": "^4.14.197",
     "@types/node": "^18.16.19",
     "@types/prompts": "^2.4.4",
     "@types/react": "^18.2.15",
-    "@types/react-dev-utils": "^9.0.11",
     "@types/react-test-renderer": "^18.0.0",
     "@types/semver": "^7.5.0",
     "@types/shelljs": "^0.8.12",
     "@typescript-eslint/eslint-plugin": "^5.62.0",
     "@typescript-eslint/parser": "^5.62.0",
     "cross-env": "^7.0.3",
-    "cspell": "^8.1.0",
+    "cspell": "^8.18.1",
     "eslint": "^8.45.0",
     "eslint-config-airbnb": "^19.0.4",
     "eslint-config-prettier": "^8.8.0",
@@ -94,23 +100,25 @@
     "eslint-plugin-jest": "^27.2.3",
     "eslint-plugin-jsx-a11y": "^6.7.1",
     "eslint-plugin-react": "^7.32.2",
+    "eslint-plugin-react-compiler": "^19.0.0-beta-40c6c23-20250301",
     "eslint-plugin-react-hooks": "^4.6.0",
     "eslint-plugin-regexp": "^1.15.0",
     "husky": "^8.0.3",
-    "image-size": "^1.0.2",
-    "jest": "^29.6.1",
-    "jest-environment-jsdom": "^29.6.1",
-    "jest-serializer-ansi-escapes": "^2.0.1",
+    "image-size": "^2.0.2",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "jest-serializer-ansi-escapes": "^3.0.0",
     "jest-serializer-react-helmet-async": "^1.0.21",
     "lerna": "^6.6.2",
     "lerna-changelog": "^2.2.0",
-    "lint-staged": "^13.2.3",
+    "lint-staged": "~13.2.3",
     "lockfile-lint": "^4.14.0",
     "npm-run-all": "^4.1.5",
+    "patch-package": "^8.0.0",
+    "postinstall-postinstall": "^2.1.0",
     "prettier": "^2.8.8",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
-    "react-helmet-async": "^1.3.0",
     "react-test-renderer": "^18.0.0",
     "rimraf": "^3.0.2",
     "sharp": "^0.32.3",
@@ -118,6 +126,7 @@
     "stylelint": "^14.16.1",
     "stylelint-config-prettier": "^9.0.5",
     "stylelint-config-standard": "^29.0.0",
-    "typescript": "~5.5.2"
-  }
+    "typescript": "~5.8.2"
+  },
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }

packages/create-docusaurus/bin/index.js

@@ -10,7 +10,7 @@
 
 import path from 'path';
 import {createRequire} from 'module';
-import logger from '@docusaurus/logger';
+import {logger} from '@docusaurus/logger';
 import semver from 'semver';
 import {program} from 'commander';
 

packages/create-docusaurus/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-docusaurus",
-  "version": "3.5.1",
+  "version": "3.7.0",
   "description": "Create Docusaurus apps easily.",
   "type": "module",
   "repository": {
@@ -22,14 +22,14 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/logger": "3.5.1",
-    "@docusaurus/utils": "3.5.1",
+    "@docusaurus/logger": "3.7.0",
+    "@docusaurus/utils": "3.7.0",
     "commander": "^5.1.0",
+    "execa": "5.1.1",
     "fs-extra": "^11.1.1",
     "lodash": "^4.17.21",
     "prompts": "^2.4.2",
     "semver": "^7.5.4",
-    "shelljs": "^0.8.5",
     "supports-color": "^9.4.0",
     "tslib": "^2.6.0"
   },

packages/create-docusaurus/src/index.ts

@@ -9,11 +9,14 @@ import fs from 'fs-extra';
 import {fileURLToPath} from 'url';
 import path from 'path';
 import _ from 'lodash';
-import logger from '@docusaurus/logger';
-import shell from 'shelljs';
+import {logger} from '@docusaurus/logger';
+import execa from 'execa';
 import prompts, {type Choice} from 'prompts';
 import supportsColor from 'supports-color';
-import {escapeShellArg, askPreferredLanguage} from '@docusaurus/utils';
+
+// TODO remove dependency on large @docusaurus/utils
+//  would be better to have a new smaller @docusaurus/utils-cli package
+import {askPreferredLanguage} from '@docusaurus/utils';
 
 type LanguagesOptions = {
   javascript?: boolean;
@@ -70,9 +73,9 @@ function findPackageManagerFromUserAgent(): PackageManager | undefined {
 }
 
 async function askForPackageManagerChoice(): Promise<PackageManager> {
-  const hasYarn = shell.exec('yarn --version', {silent: true}).code === 0;
-  const hasPnpm = shell.exec('pnpm --version', {silent: true}).code === 0;
-  const hasBun = shell.exec('bun --version', {silent: true}).code === 0;
+  const hasYarn = (await execa.command('yarn --version')).exitCode === 0;
+  const hasPnpm = (await execa.command('pnpm --version')).exitCode === 0;
+  const hasBun = (await execa.command('bun --version')).exitCode === 0;
 
   if (!hasYarn && !hasPnpm && !hasBun) {
     return 'npm';
@@ -530,10 +533,7 @@ export default async function init(
 
   if (source.type === 'git') {
     const gitCommand = await getGitCommand(source.strategy);
-    const gitCloneCommand = `${gitCommand} ${escapeShellArg(
-      source.url,
-    )} ${escapeShellArg(dest)}`;
-    if (shell.exec(gitCloneCommand).code !== 0) {
+    if ((await execa(gitCommand, [source.url, dest])).exitCode !== 0) {
       logger.error`Cloning Git template failed!`;
       process.exit(1);
     }
@@ -583,24 +583,27 @@ export default async function init(
   const cdpath = path.relative('.', dest);
   const pkgManager = await getPackageManager(dest, cliOptions);
   if (!cliOptions.skipInstall) {
-    shell.cd(dest);
+    process.chdir(dest);
     logger.info`Installing dependencies with name=${pkgManager}...`;
+    // ...
+
     if (
-      shell.exec(
-        pkgManager === 'yarn'
-          ? 'yarn'
-          : pkgManager === 'bun'
-          ? 'bun install'
-          : `${pkgManager} install --color always`,
-        {
-          env: {
-            ...process.env,
-            // Force coloring the output, since the command is invoked by
-            // shelljs, which is not an interactive shell
-            ...(supportsColor.stdout ? {FORCE_COLOR: '1'} : {}),
+      (
+        await execa.command(
+          pkgManager === 'yarn'
+            ? 'yarn'
+            : pkgManager === 'bun'
+            ? 'bun install'
+            : `${pkgManager} install --color always`,
+          {
+            env: {
+              ...process.env,
+              // Force coloring the output
+              ...(supportsColor.stdout ? {FORCE_COLOR: '1'} : {}),
+            },
           },
-        },
-      ).code !== 0
+        )
+      ).exitCode !== 0
     ) {
       logger.error('Dependency installation failed.');
       logger.info`The site directory has already been created, and you can retry by typing:

packages/create-docusaurus/templates/classic-typescript/docusaurus.config.ts

@@ -2,11 +2,18 @@ import {themes as prismThemes} from 'prism-react-renderer';
 import type {Config} from '@docusaurus/types';
 import type * as Preset from '@docusaurus/preset-classic';
 
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
 const config: Config = {
   title: 'My Site',
   tagline: 'Dinosaurs are cool',
   favicon: 'img/favicon.ico',
 
+  // Future flags, see https://docusaurus.io/docs/api/docusaurus-config#future
+  future: {
+    v4: true, // Improve compatibility with the upcoming Docusaurus v4
+  },
+
   // Set the production url of your site here
   url: 'https://your-docusaurus-site.example.com',
   // Set the /<baseUrl>/ pathname under which your site is served
@@ -110,8 +117,8 @@ const config: Config = {
               href: 'https://discordapp.com/invite/docusaurus',
             },
             {
-              label: 'Twitter',
-              href: 'https://twitter.com/docusaurus',
+              label: 'X',
+              href: 'https://x.com/docusaurus',
             },
           ],
         },

packages/create-docusaurus/templates/classic-typescript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-2-classic-typescript-template",
-  "version": "3.5.1",
+  "version": "3.7.0",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
@@ -15,19 +15,19 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@docusaurus/core": "3.5.1",
-    "@docusaurus/preset-classic": "3.5.1",
+    "@docusaurus/core": "3.7.0",
+    "@docusaurus/preset-classic": "3.7.0",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.5.1",
-    "@docusaurus/tsconfig": "3.5.1",
-    "@docusaurus/types": "3.5.1",
-    "typescript": "~5.5.2"
+    "@docusaurus/module-type-aliases": "3.7.0",
+    "@docusaurus/tsconfig": "3.7.0",
+    "@docusaurus/types": "3.7.0",
+    "typescript": "~5.6.2"
   },
   "browserslist": {
     "production": [

packages/create-docusaurus/templates/classic-typescript/sidebars.ts

@@ -1,5 +1,7 @@
 import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
 
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
 /**
  * Creating a sidebar enables you to:
  - create an ordered group of docs

packages/create-docusaurus/templates/classic-typescript/src/components/HomepageFeatures/index.tsx

@@ -1,3 +1,4 @@
+import type {ReactNode} from 'react';
 import clsx from 'clsx';
 import Heading from '@theme/Heading';
 import styles from './styles.module.css';
@@ -5,7 +6,7 @@ import styles from './styles.module.css';
 type FeatureItem = {
   title: string;
   Svg: React.ComponentType<React.ComponentProps<'svg'>>;
-  description: JSX.Element;
+  description: ReactNode;
 };
 
 const FeatureList: FeatureItem[] = [
@@ -55,7 +56,7 @@ function Feature({title, Svg, description}: FeatureItem) {
   );
 }
 
-export default function HomepageFeatures(): JSX.Element {
+export default function HomepageFeatures(): ReactNode {
   return (
     <section className={styles.features}>
       <div className="container">

packages/create-docusaurus/templates/classic-typescript/src/pages/index.tsx

@@ -1,3 +1,4 @@
+import type {ReactNode} from 'react';
 import clsx from 'clsx';
 import Link from '@docusaurus/Link';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
@@ -28,7 +29,7 @@ function HomepageHeader() {
   );
 }
 
-export default function Home(): JSX.Element {
+export default function Home(): ReactNode {
   const {siteConfig} = useDocusaurusContext();
   return (
     <Layout

packages/create-docusaurus/templates/classic-typescript/tsconfig.json

@@ -3,5 +3,6 @@
   "extends": "@docusaurus/tsconfig",
   "compilerOptions": {
     "baseUrl": "."
-  }
+  },
+  "exclude": [".docusaurus", "build"]
 }

packages/create-docusaurus/templates/classic/docusaurus.config.js

@@ -6,12 +6,19 @@
 
 import {themes as prismThemes} from 'prism-react-renderer';
 
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
 /** @type {import('@docusaurus/types').Config} */
 const config = {
   title: 'My Site',
   tagline: 'Dinosaurs are cool',
   favicon: 'img/favicon.ico',
 
+  // Future flags, see https://docusaurus.io/docs/api/docusaurus-config#future
+  future: {
+    v4: true, // Improve compatibility with the upcoming Docusaurus v4
+  },
+
   // Set the production url of your site here
   url: 'https://your-docusaurus-site.example.com',
   // Set the /<baseUrl>/ pathname under which your site is served
@@ -118,8 +125,8 @@ const config = {
                 href: 'https://discordapp.com/invite/docusaurus',
               },
               {
-                label: 'Twitter',
-                href: 'https://twitter.com/docusaurus',
+                label: 'X',
+                href: 'https://x.com/docusaurus',
               },
             ],
           },

packages/create-docusaurus/templates/classic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-2-classic-template",
-  "version": "3.5.1",
+  "version": "3.7.0",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
@@ -14,17 +14,17 @@
     "write-heading-ids": "docusaurus write-heading-ids"
   },
   "dependencies": {
-    "@docusaurus/core": "3.5.1",
-    "@docusaurus/preset-classic": "3.5.1",
+    "@docusaurus/core": "3.7.0",
+    "@docusaurus/preset-classic": "3.7.0",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.5.1",
-    "@docusaurus/types": "3.5.1"
+    "@docusaurus/module-type-aliases": "3.7.0",
+    "@docusaurus/types": "3.7.0"
   },
   "browserslist": {
     "production": [

packages/create-docusaurus/templates/classic/sidebars.js

@@ -1,3 +1,7 @@
+// @ts-check
+
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
 /**
  * Creating a sidebar enables you to:
  - create an ordered group of docs
@@ -7,11 +11,9 @@
  The sidebars can be generated from the filesystem, or explicitly defined here.
 
  Create as many sidebars as you want.
+
+ @type {import('@docusaurus/plugin-content-docs').SidebarsConfig}
  */
-
-// @ts-check
-
-/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
   tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],

packages/create-docusaurus/templates/shared/README.md

@@ -4,13 +4,13 @@ This website is built using [Docusaurus](https://docusaurus.io/), a modern stati
 
 ### Installation
 
-```
+```bash
 $ yarn
 ```
 
 ### Local Development
 
-```
+```bash
 $ yarn start
 ```
 
@@ -18,7 +18,7 @@ This command starts a local development server and opens up a browser window. Mo
 
 ### Build
 
-```
+```bash
 $ yarn build
 ```
 
@@ -28,13 +28,13 @@ This command generates static content into the `build` directory and can be serv
 
 Using SSH:
 
-```
+```bash
 $ USE_SSH=true yarn deploy
 ```
 
 Not using SSH:
 
-```
+```bash
 $ GIT_USER=<Your GitHub username> yarn deploy
 ```
 

packages/create-docusaurus/templates/shared/babel.config.js

@@ -1,3 +0,0 @@
-module.exports = {
-  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
-};

packages/create-docusaurus/templates/shared/blog/authors.yml

@@ -1,12 +1,14 @@
 yangshun:
   name: Yangshun Tay
-  title: Front End Engineer @ Facebook
-  url: https://github.com/yangshun
+  title: Ex-Meta Staff Engineer, Co-founder GreatFrontEnd
+  url: https://linkedin.com/in/yangshun
   image_url: https://github.com/yangshun.png
   page: true
   socials:
     x: yangshunz
+    linkedin: yangshun
     github: yangshun
+    newsletter: https://www.greatfrontend.com
 
 slorber:
   name: Sébastien Lorber

packages/docusaurus-babel/.npmignore

@@ -0,0 +1,3 @@
+.tsbuildinfo*
+tsconfig*
+__tests__

packages/docusaurus-babel/README.md

@@ -0,0 +1,3 @@
+# `@docusaurus/babel`
+
+Docusaurus package for Babel-related utils.

packages/docusaurus-babel/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@docusaurus/babel",
+  "version": "3.7.0",
+  "description": "Docusaurus package for Babel-related utils.",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    "./preset": {
+      "types": "./lib/preset.d.ts",
+      "default": "./lib/preset.js"
+    },
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/facebook/docusaurus.git",
+    "directory": "packages/docusaurus-babel"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@babel/core": "^7.25.9",
+    "@babel/generator": "^7.25.9",
+    "@babel/plugin-syntax-dynamic-import": "^7.8.3",
+    "@babel/plugin-transform-runtime": "^7.25.9",
+    "@babel/preset-env": "^7.25.9",
+    "@babel/preset-react": "^7.25.9",
+    "@babel/preset-typescript": "^7.25.9",
+    "@babel/runtime": "^7.25.9",
+    "@babel/runtime-corejs3": "^7.25.9",
+    "@babel/traverse": "^7.25.9",
+    "@docusaurus/logger": "3.7.0",
+    "@docusaurus/utils": "3.7.0",
+    "babel-plugin-dynamic-import-node": "^2.3.3",
+    "fs-extra": "^11.1.1",
+    "tslib": "^2.6.0"
+  },
+  "engines": {
+    "node": ">=18.0"
+  }
+}

packages/docusaurus-babel/src/__tests__/babelTranslationsExtractor.test.ts

@@ -0,0 +1,537 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {jest} from '@jest/globals';
+import fs from 'fs-extra';
+import tmp from 'tmp-promise';
+import {getBabelOptions} from '../utils';
+import {extractSourceCodeFileTranslations} from '../babelTranslationsExtractor';
+
+const TestBabelOptions = getBabelOptions({
+  isServer: true,
+});
+
+async function createTmpSourceCodeFile({
+  extension,
+  content,
+}: {
+  extension: string;
+  content: string;
+}) {
+  const file = await tmp.file({
+    prefix: 'jest-createTmpSourceCodeFile',
+    postfix: `.${extension}`,
+  });
+
+  await fs.writeFile(file.path, content);
+
+  return {
+    sourceCodeFilePath: file.path,
+  };
+}
+
+describe('extractSourceCodeFileTranslations', () => {
+  it('throws for bad source code', async () => {
+    const {sourceCodeFilePath} = await createTmpSourceCodeFile({
+      extension: 'js',
+      content: `
+const default => {
+
+}
+`,
+    });
+
+    const errorMock = jest.spyOn(console, 'error').mockImplementation(() => {});
+
+    await expect(
+      extractSourceCodeFileTranslations(sourceCodeFilePath, TestBabelOptions),
+    ).rejects.toThrow();
+
+    expect(errorMock).toHaveBeenCalledWith(
+      expect.stringMatching(
+        /Error while attempting to extract Docusaurus translations from source code file at/,
+      ),
+    );
+  });
+
+  it('extracts nothing from untranslated source code', async () => {
+    const {sourceCodeFilePath} = await createTmpSourceCodeFile({
+      extension: 'js',
+      content: `
+const unrelated =  42;
+`,
+    });
+
+    const sourceCodeFileTranslations = await extractSourceCodeFileTranslations(
+      sourceCodeFilePath,
+      TestBabelOptions,
+    );
+
+    expect(sourceCodeFileTranslations).toEqual({
+      sourceCodeFilePath,
+      translations: {},
+      warnings: [],
+    });
+  });
+
+  it('extracts from a translate() functions calls', async () => {
+    const {sourceCodeFilePath} = await createTmpSourceCodeFile({
+      extension: 'js',
+      content: `
+import {translate} from '@docusaurus/Translate';
+
+export default function MyComponent() {
+  return (
+    <div>
+      <input text={translate({id: 'codeId',message: 'code message',description: 'code description'})}/>
+
+      <input text={translate({id: 'codeId1'})}/>
+    </div>
+  );
+}
+`,
+    });
+
+    const sourceCodeFileTranslations = await extractSourceCodeFileTranslations(
+      sourceCodeFilePath,
+      TestBabelOptions,
+    );
+
+    expect(sourceCodeFileTranslations).toEqual({
+      sourceCodeFilePath,
+      translations: {
+        codeId: {message: 'code message', description: 'code description'},
+        codeId1: {message: 'codeId1'},
+      },
+      warnings: [],
+    });
+  });
+
+  it('extracts from a <Translate> components', async () => {
+    const {sourceCodeFilePath} = await createTmpSourceCodeFile({
+      extension: 'js',
+      content: `
+import Translate from '@docusaurus/Translate';
+
+export default function MyComponent() {
+  return (
+    <div>
+      <Translate id="codeId" description={"code description"}>
+        code message
+      </Translate>
+
+      <Translate id="codeId1" description="description 2" />
+    </div>
+  );
+}
+`,
+    });
+
+    const sourceCodeFileTranslations = await extractSourceCodeFileTranslations(
+      sourceCodeFilePath,
+      TestBabelOptions,
+    );
+
+    expect(sourceCodeFileTranslations).toEqual({
+      sourceCodeFilePath,
+      translations: {
+        codeId: {message: 'code message', description: 'code description'},
+        codeId1: {message: 'codeId1', description: 'description 2'},
+      },
+      warnings: [],
+    });
+  });
+
+  it('extracts statically evaluable content', async () => {
+    const {sourceCodeFilePath} = await createTmpSourceCodeFile({
+      extension: 'js',
+      content: `
+import Translate, {translate} from '@docusaurus/Translate';
+
+const prefix = "prefix ";
+
+export default function MyComponent() {
+  return (
+    <div>
+      <input
+        text={translate({
+          id: prefix + 'codeId fn',
+          message: prefix + 'code message',
+          description: prefix + 'code description'}
+        )}
+      />
+      <Translate
+        id={prefix + "codeId comp"}
+        description={prefix + "code description"}
+      >
+      {prefix + "code message"}
+      </Translate>
+      <Translate>
+
+        {
+
+          prefix + \`Static template literal with unusual formatting!\`
+        }
+      </Translate>
+    </div>
+  );
+}
+`,
+    });
+
+    const sourceCodeFileTranslations = await extractSourceCodeFileTranslations(
+      sourceCodeFilePath,
+      TestBabelOptions,
+    );
+
+    expect(sourceCodeFileTranslations).toEqual({
+      sourceCodeFilePath,
+      translations: {
+        'prefix codeId comp': {
+          message: 'prefix code message',
+          description: 'prefix code description',
+        },
+        'prefix codeId fn': {
+          message: 'prefix code message',
+          description: 'prefix code description',
+        },
+        'prefix Static template literal with unusual formatting!': {
+          message: 'prefix Static template literal with unusual formatting!',
+        },
+      },
+      warnings: [],
+    });
+  });
+
+  it('extracts from TypeScript file', async () => {
+    const {sourceCodeFilePath} = await createTmpSourceCodeFile({
+      extension: 'tsx',
+      content: `
+import {translate} from '@docusaurus/Translate';
+
+type ComponentProps<T> = {toto: string}
+
+export default function MyComponent<T>(props: ComponentProps<T>) {
+  return (
+    <div>
+      <input text={translate({id: 'codeId',message: 'code message',description: 'code description'}) as string}/>
+      <input text={translate({message: 'code message 2',description: 'code description 2'}) as string}/>
+    </div>
+  );
+}
+`,
+    });
+
+    const sourceCodeFileTranslations = await extractSourceCodeFileTranslations(
+      sourceCodeFilePath,
+      TestBabelOptions,
+    );
+
+    expect(sourceCodeFileTranslations).toEqual({
+      sourceCodeFilePath,
+      translations: {
+        codeId: {message: 'code message', description: 'code description'},
+        'code message 2': {
+          message: 'code message 2',
+          description: 'code description 2',
+        },
+      },
+      warnings: [],
+    });
+  });
+
+  it('does not extract from functions that is not docusaurus provided', async () => {
+    const {sourceCodeFilePath} = await createTmpSourceCodeFile({
+      extension: 'js',
+      content: `
+import translate from 'a-lib';
+
+export default function somethingElse() {
+  const a = translate('foo');
+  return <Translate>bar</Translate>
+}
+`,
+    });
+
+    const sourceCodeFileTranslations = await extractSourceCodeFileTranslations(
+      sourceCodeFilePath,
+      TestBabelOptions,
+    );
+
+    expect(sourceCodeFileTranslations).toEqual({
+      sourceCodeFilePath,
+      translations: {},
+      warnings: [],
+    });
+  });
+
+  it('does not extract from functions that is internal', async () => {
+    const {sourceCodeFilePath} = await createTmpSourceCodeFile({
+      extension: 'js',
+      content: `
+function translate() {
+  return 'foo'
+}
+
+export default function somethingElse() {
+  const a = translate('foo');
+  return a;
+}
+`,
+    });
+
+    const sourceCodeFileTranslations = await extractSourceCodeFileTranslations(
+      sourceCodeFilePath,
+      TestBabelOptions,
+    );
+
+    expect(sourceCodeFileTranslations).toEqual({
+      sourceCodeFilePath,
+      translations: {},
+      warnings: [],
+    });
+  });
+
+  it('recognizes aliased imports', async () => {
+    const {sourceCodeFilePath} = await createTmpSourceCodeFile({
+      extension: 'js',
+      content: `
+import Foo, {translate as bar} from '@docusaurus/Translate';
+
+export function MyComponent() {
+  return (
+    <div>
+      <Foo id="codeId" description={"code description"}>
+        code message
+      </Foo>
+
+      <Translate id="codeId1" />
+    </div>
+  );
+}
+
+export default function () {
+  return (
+    <div>
+      <input text={translate({id: 'codeId',message: 'code message',description: 'code description'})}/>
+
+      <input text={bar({id: 'codeId1'})}/>
+    </div>
+  );
+}
+`,
+    });
+
+    const sourceCodeFileTranslations = await extractSourceCodeFileTranslations(
+      sourceCodeFilePath,
+      TestBabelOptions,
+    );
+
+    expect(sourceCodeFileTranslations).toEqual({
+      sourceCodeFilePath,
+      translations: {
+        codeId: {
+          description: 'code description',
+          message: 'code message',
+        },
+        codeId1: {
+          message: 'codeId1',
+        },
+      },
+      warnings: [],
+    });
+  });
+
+  it('recognizes aliased imports as string literal', async () => {
+    const {sourceCodeFilePath} = await createTmpSourceCodeFile({
+      extension: 'js',
+      content: `
+import {'translate' as bar} from '@docusaurus/Translate';
+
+export default function () {
+  return (
+    <div>
+      <input text={translate({id: 'codeId',message: 'code message',description: 'code description'})}/>
+
+      <input text={bar({id: 'codeId1'})}/>
+    </div>
+  );
+}
+`,
+    });
+
+    const sourceCodeFileTranslations = await extractSourceCodeFileTranslations(
+      sourceCodeFilePath,
+      TestBabelOptions,
+    );
+
+    expect(sourceCodeFileTranslations).toEqual({
+      sourceCodeFilePath,
+      translations: {
+        codeId1: {
+          message: 'codeId1',
+        },
+      },
+      warnings: [],
+    });
+  });
+
+  it('warns about id if no children', async () => {
+    const {sourceCodeFilePath} = await createTmpSourceCodeFile({
+      extension: 'js',
+      content: `
+import Translate from '@docusaurus/Translate';
+
+export default function () {
+  return (
+    <Translate description="foo" />
+  );
+}
+`,
+    });
+
+    const sourceCodeFileTranslations = await extractSourceCodeFileTranslations(
+      sourceCodeFilePath,
+      TestBabelOptions,
+    );
+
+    expect(sourceCodeFileTranslations).toEqual({
+      sourceCodeFilePath,
+      translations: {},
+      warnings: [
+        `<Translate> without children must have id prop.
+Example: <Translate id="my-id" />
+File: ${sourceCodeFilePath} at line 6
+Full code: <Translate description="foo" />`,
+      ],
+    });
+  });
+
+  it('warns about dynamic id', async () => {
+    const {sourceCodeFilePath} = await createTmpSourceCodeFile({
+      extension: 'js',
+      content: `
+import Translate from '@docusaurus/Translate';
+
+export default function () {
+  return (
+    <Translate id={index}>foo</Translate>
+  );
+}
+`,
+    });
+
+    const sourceCodeFileTranslations = await extractSourceCodeFileTranslations(
+      sourceCodeFilePath,
+      TestBabelOptions,
+    );
+
+    expect(sourceCodeFileTranslations).toEqual({
+      sourceCodeFilePath,
+      translations: {
+        foo: {
+          message: 'foo',
+        },
+      },
+      warnings: [
+        `<Translate> prop=id should be a statically evaluable object.
+Example: <Translate id="optional id" description="optional description">Message</Translate>
+Dynamically constructed values are not allowed, because they prevent translations to be extracted.
+File: ${sourceCodeFilePath} at line 6
+Full code: <Translate id={index}>foo</Translate>`,
+      ],
+    });
+  });
+
+  it('warns about dynamic children', async () => {
+    const {sourceCodeFilePath} = await createTmpSourceCodeFile({
+      extension: 'js',
+      content: `
+import Translate from '@docusaurus/Translate';
+
+export default function () {
+  return (
+    <Translate id='foo'><a>hhh</a></Translate>
+  );
+}
+`,
+    });
+
+    const sourceCodeFileTranslations = await extractSourceCodeFileTranslations(
+      sourceCodeFilePath,
+      TestBabelOptions,
+    );
+
+    expect(sourceCodeFileTranslations).toEqual({
+      sourceCodeFilePath,
+      translations: {},
+      warnings: [
+        `Translate content could not be extracted. It has to be a static string and use optional but static props, like <Translate id="my-id" description="my-description">text</Translate>.
+File: ${sourceCodeFilePath} at line 6
+Full code: <Translate id='foo'><a>hhh</a></Translate>`,
+      ],
+    });
+  });
+
+  it('warns about dynamic translate argument', async () => {
+    const {sourceCodeFilePath} = await createTmpSourceCodeFile({
+      extension: 'js',
+      content: `
+import {translate} from '@docusaurus/Translate';
+
+translate(foo);
+`,
+    });
+
+    const sourceCodeFileTranslations = await extractSourceCodeFileTranslations(
+      sourceCodeFilePath,
+      TestBabelOptions,
+    );
+
+    expect(sourceCodeFileTranslations).toEqual({
+      sourceCodeFilePath,
+      translations: {},
+      warnings: [
+        `translate() first arg should be a statically evaluable object.
+Example: translate({message: "text",id: "optional.id",description: "optional description"}
+Dynamically constructed values are not allowed, because they prevent translations to be extracted.
+File: ${sourceCodeFilePath} at line 4
+Full code: translate(foo)`,
+      ],
+    });
+  });
+
+  it('warns about too many arguments', async () => {
+    const {sourceCodeFilePath} = await createTmpSourceCodeFile({
+      extension: 'js',
+      content: `
+import {translate} from '@docusaurus/Translate';
+
+translate({message: 'a'}, {a: 1}, 2);
+`,
+    });
+
+    const sourceCodeFileTranslations = await extractSourceCodeFileTranslations(
+      sourceCodeFilePath,
+      TestBabelOptions,
+    );
+
+    expect(sourceCodeFileTranslations).toEqual({
+      sourceCodeFilePath,
+      translations: {},
+      warnings: [
+        `translate() function only takes 1 or 2 args
+File: ${sourceCodeFilePath} at line 4
+Full code: translate({
+  message: 'a'
+}, {
+  a: 1
+}, 2)`,
+      ],
+    });
+  });
+});

packages/docusaurus-babel/src/babelTranslationsExtractor.ts

@@ -0,0 +1,266 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import fs from 'fs-extra';
+import logger from '@docusaurus/logger';
+import traverse, {type Node} from '@babel/traverse';
+import generate from '@babel/generator';
+import {
+  parse,
+  type types as t,
+  type NodePath,
+  type TransformOptions,
+} from '@babel/core';
+import type {TranslationFileContent} from '@docusaurus/types';
+
+export type SourceCodeFileTranslations = {
+  sourceCodeFilePath: string;
+  translations: TranslationFileContent;
+  warnings: string[];
+};
+
+export async function extractAllSourceCodeFileTranslations(
+  sourceCodeFilePaths: string[],
+  babelOptions: TransformOptions,
+): Promise<SourceCodeFileTranslations[]> {
+  return Promise.all(
+    sourceCodeFilePaths.flatMap((sourceFilePath) =>
+      extractSourceCodeFileTranslations(sourceFilePath, babelOptions),
+    ),
+  );
+}
+
+export async function extractSourceCodeFileTranslations(
+  sourceCodeFilePath: string,
+  babelOptions: TransformOptions,
+): Promise<SourceCodeFileTranslations> {
+  try {
+    const code = await fs.readFile(sourceCodeFilePath, 'utf8');
+
+    const ast = parse(code, {
+      ...babelOptions,
+      ast: true,
+      // filename is important, because babel does not process the same files
+      // according to their js/ts extensions.
+      // See https://x.com/NicoloRibaudo/status/1321130735605002243
+      filename: sourceCodeFilePath,
+    }) as Node;
+
+    const translations = extractSourceCodeAstTranslations(
+      ast,
+      sourceCodeFilePath,
+    );
+    return translations;
+  } catch (err) {
+    logger.error`Error while attempting to extract Docusaurus translations from source code file at path=${sourceCodeFilePath}.`;
+    throw err;
+  }
+}
+
+/*
+Need help understanding this?
+
+Useful resources:
+https://github.com/jamiebuilds/babel-handbook/blob/master/translations/en/plugin-handbook.md
+https://github.com/formatjs/formatjs/blob/main/packages/babel-plugin-formatjs/index.ts
+https://github.com/pugjs/babel-walk
+ */
+function extractSourceCodeAstTranslations(
+  ast: Node,
+  sourceCodeFilePath: string,
+): SourceCodeFileTranslations {
+  function sourceWarningPart(node: Node) {
+    return `File: ${sourceCodeFilePath} at line ${node.loc?.start.line ?? '?'}
+Full code: ${generate(node).code}`;
+  }
+
+  const translations: TranslationFileContent = {};
+  const warnings: string[] = [];
+  let translateComponentName: string | undefined;
+  let translateFunctionName: string | undefined;
+
+  // First pass: find import declarations of Translate / translate.
+  // If not found, don't process the rest to avoid false positives
+  traverse(ast, {
+    ImportDeclaration(path) {
+      if (
+        path.node.importKind === 'type' ||
+        path.get('source').node.value !== '@docusaurus/Translate'
+      ) {
+        return;
+      }
+      const importSpecifiers = path.get('specifiers');
+      const defaultImport = importSpecifiers.find(
+        (specifier): specifier is NodePath<t.ImportDefaultSpecifier> =>
+          specifier.node.type === 'ImportDefaultSpecifier',
+      );
+      const callbackImport = importSpecifiers.find(
+        (specifier): specifier is NodePath<t.ImportSpecifier> =>
+          specifier.node.type === 'ImportSpecifier' &&
+          ((
+            (specifier as NodePath<t.ImportSpecifier>).get('imported')
+              .node as t.Identifier
+          ).name === 'translate' ||
+            (
+              (specifier as NodePath<t.ImportSpecifier>).get('imported')
+                .node as t.StringLiteral
+            ).value === 'translate'),
+      );
+
+      translateComponentName = defaultImport?.get('local').node.name;
+      translateFunctionName = callbackImport?.get('local').node.name;
+    },
+  });
+
+  traverse(ast, {
+    ...(translateComponentName && {
+      JSXElement(path) {
+        if (
+          !path
+            .get('openingElement')
+            .get('name')
+            .isJSXIdentifier({name: translateComponentName})
+        ) {
+          return;
+        }
+        function evaluateJSXProp(propName: string): string | undefined {
+          const attributePath = path
+            .get('openingElement.attributes')
+            .find(
+              (attr) =>
+                attr.isJSXAttribute() &&
+                attr.get('name').isJSXIdentifier({name: propName}),
+            );
+
+          if (attributePath) {
+            const attributeValue = attributePath.get('value') as NodePath;
+
+            const attributeValueEvaluated =
+              attributeValue.isJSXExpressionContainer()
+                ? (attributeValue.get('expression') as NodePath).evaluate()
+                : attributeValue.evaluate();
+
+            if (
+              attributeValueEvaluated.confident &&
+              typeof attributeValueEvaluated.value === 'string'
+            ) {
+              return attributeValueEvaluated.value;
+            }
+            warnings.push(
+              `<Translate> prop=${propName} should be a statically evaluable object.
+Example: <Translate id="optional id" description="optional description">Message</Translate>
+Dynamically constructed values are not allowed, because they prevent translations to be extracted.
+${sourceWarningPart(path.node)}`,
+            );
+          }
+
+          return undefined;
+        }
+
+        const id = evaluateJSXProp('id');
+        const description = evaluateJSXProp('description');
+        let message: string;
+        const childrenPath = path.get('children');
+
+        // Handle empty content
+        if (!childrenPath.length) {
+          if (!id) {
+            warnings.push(`<Translate> without children must have id prop.
+Example: <Translate id="my-id" />
+${sourceWarningPart(path.node)}`);
+          } else {
+            translations[id] = {
+              message: id,
+              ...(description && {description}),
+            };
+          }
+
+          return;
+        }
+
+        // Handle single non-empty content
+        const singleChildren = childrenPath
+          // Remove empty/useless text nodes that might be around our
+          // translation! Makes the translation system more reliable to JSX
+          // formatting issues
+          .filter(
+            (children) =>
+              !(
+                children.isJSXText() &&
+                children.node.value.replace('\n', '').trim() === ''
+              ),
+          )
+          .pop();
+        const isJSXText = singleChildren?.isJSXText();
+        const isJSXExpressionContainer =
+          singleChildren?.isJSXExpressionContainer() &&
+          (singleChildren.get('expression') as NodePath).evaluate().confident;
+
+        if (isJSXText || isJSXExpressionContainer) {
+          message = isJSXText
+            ? singleChildren.node.value.trim().replace(/\s+/g, ' ')
+            : String(
+                (singleChildren.get('expression') as NodePath).evaluate().value,
+              );
+
+          translations[id ?? message] = {
+            message,
+            ...(description && {description}),
+          };
+        } else {
+          warnings.push(
+            `Translate content could not be extracted. It has to be a static string and use optional but static props, like <Translate id="my-id" description="my-description">text</Translate>.
+${sourceWarningPart(path.node)}`,
+          );
+        }
+      },
+    }),
+
+    ...(translateFunctionName && {
+      CallExpression(path) {
+        if (!path.get('callee').isIdentifier({name: translateFunctionName})) {
+          return;
+        }
+
+        const args = path.get('arguments');
+        if (args.length === 1 || args.length === 2) {
+          const firstArgPath = args[0]!;
+
+          // translate("x" + "y"); => translate("xy");
+          const firstArgEvaluated = firstArgPath.evaluate();
+
+          if (
+            firstArgEvaluated.confident &&
+            typeof firstArgEvaluated.value === 'object'
+          ) {
+            const {message, id, description} = firstArgEvaluated.value as {
+              [propName: string]: unknown;
+            };
+            translations[String(id ?? message)] = {
+              message: String(message ?? id),
+              ...(Boolean(description) && {description: String(description)}),
+            };
+          } else {
+            warnings.push(
+              `translate() first arg should be a statically evaluable object.
+Example: translate({message: "text",id: "optional.id",description: "optional description"}
+Dynamically constructed values are not allowed, because they prevent translations to be extracted.
+${sourceWarningPart(path.node)}`,
+            );
+          }
+        } else {
+          warnings.push(
+            `translate() function only takes 1 or 2 args
+${sourceWarningPart(path.node)}`,
+          );
+        }
+      },
+    }),
+  });
+
+  return {sourceCodeFilePath, translations, warnings};
+}

packages/docusaurus-babel/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+export {getCustomBabelConfigFilePath, getBabelOptions} from './utils';
+
+export {extractAllSourceCodeFileTranslations} from './babelTranslationsExtractor';

packages/docusaurus-babel/src/preset.ts

@@ -0,0 +1,82 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import path from 'path';
+import type {ConfigAPI, TransformOptions} from '@babel/core';
+
+function getTransformOptions(isServer: boolean): TransformOptions {
+  const absoluteRuntimePath = path.dirname(
+    require.resolve(`@babel/runtime/package.json`),
+  );
+  return {
+    // All optional newlines and whitespace will be omitted when generating code
+    // in compact mode
+    compact: true,
+    presets: [
+      isServer
+        ? [
+            require.resolve('@babel/preset-env'),
+            {
+              targets: {
+                node: 'current',
+              },
+            },
+          ]
+        : [
+            require.resolve('@babel/preset-env'),
+            {
+              useBuiltIns: 'entry',
+              loose: true,
+              corejs: '3',
+              // Do not transform modules to CJS
+              modules: false,
+              // Exclude transforms that make all code slower
+              exclude: ['transform-typeof-symbol'],
+            },
+          ],
+      [
+        require.resolve('@babel/preset-react'),
+        {
+          runtime: 'automatic',
+        },
+      ],
+      require.resolve('@babel/preset-typescript'),
+    ],
+    plugins: [
+      // Polyfills the runtime needed for async/await, generators, and friends
+      // https://babeljs.io/docs/en/babel-plugin-transform-runtime
+      [
+        require.resolve('@babel/plugin-transform-runtime'),
+        {
+          corejs: false,
+          helpers: true,
+          // By default, it assumes @babel/runtime@7.0.0. Since we use >7.0.0,
+          // better to explicitly specify the version so that it can reuse the
+          // helper better. See https://github.com/babel/babel/issues/10261
+          // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
+          version: (require('@babel/runtime/package.json') as {version: string})
+            .version,
+          regenerator: true,
+          useESModules: true,
+          // Undocumented option that lets us encapsulate our runtime, ensuring
+          // the correct version is used
+          // https://github.com/babel/babel/blob/090c364a90fe73d36a30707fc612ce037bdbbb24/packages/babel-plugin-transform-runtime/src/index.js#L35-L42
+          absoluteRuntime: absoluteRuntimePath,
+        },
+      ],
+      // Adds syntax support for import()
+      isServer
+        ? require.resolve('babel-plugin-dynamic-import-node')
+        : require.resolve('@babel/plugin-syntax-dynamic-import'),
+    ],
+  };
+}
+
+export default function babelPresets(api: ConfigAPI): TransformOptions {
+  const callerName = api.caller((caller) => caller?.name);
+  return getTransformOptions(callerName === 'server');
+}

packages/docusaurus-babel/src/utils.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import {BABEL_CONFIG_FILE_NAME} from '@docusaurus/utils';
+import type {TransformOptions} from '@babel/core';
+
+export async function getCustomBabelConfigFilePath(
+  siteDir: string,
+): Promise<string | undefined> {
+  const customBabelConfigurationPath = path.join(
+    siteDir,
+    BABEL_CONFIG_FILE_NAME,
+  );
+  return (await fs.pathExists(customBabelConfigurationPath))
+    ? customBabelConfigurationPath
+    : undefined;
+}
+
+export function getBabelOptions({
+  isServer,
+  babelOptions,
+}: {
+  isServer?: boolean;
+  // TODO Docusaurus v4 fix this
+  //  weird to have getBabelOptions take a babelOptions param
+  babelOptions?: TransformOptions | string;
+} = {}): TransformOptions {
+  const caller = {name: isServer ? 'server' : 'client'};
+  if (typeof babelOptions === 'string') {
+    return {
+      babelrc: false,
+      configFile: babelOptions,
+      caller,
+    };
+  }
+  return {
+    ...(babelOptions ?? {
+      presets: [require.resolve('@docusaurus/babel/preset')],
+    }),
+    babelrc: false,
+    configFile: false,
+    caller,
+  };
+}

packages/docusaurus-babel/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "sourceMap": true,
+    "declarationMap": true
+  },
+  "include": ["src"],
+  "exclude": ["**/__tests__/**"]
+}

packages/docusaurus-bundler/.npmignore

@@ -0,0 +1,3 @@
+.tsbuildinfo*
+tsconfig*
+__tests__

packages/docusaurus-bundler/README.md

@@ -0,0 +1,3 @@
+# `@docusaurus/bundler`
+
+Docusaurus util package to abstract the current bundler.

packages/docusaurus-bundler/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@docusaurus/bundler",
+  "version": "3.7.0",
+  "description": "Docusaurus util package to abstract the current bundler.",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/facebook/docusaurus.git",
+    "directory": "packages/docusaurus-bundler"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@babel/core": "^7.25.9",
+    "@docusaurus/babel": "3.7.0",
+    "@docusaurus/cssnano-preset": "3.7.0",
+    "@docusaurus/logger": "3.7.0",
+    "@docusaurus/types": "3.7.0",
+    "@docusaurus/utils": "3.7.0",
+    "babel-loader": "^9.2.1",
+    "clean-css": "^5.3.2",
+    "copy-webpack-plugin": "^11.0.0",
+    "css-loader": "^6.8.1",
+    "css-minimizer-webpack-plugin": "^5.0.1",
+    "cssnano": "^6.1.2",
+    "file-loader": "^6.2.0",
+    "html-minifier-terser": "^7.2.0",
+    "mini-css-extract-plugin": "^2.9.1",
+    "null-loader": "^4.0.1",
+    "postcss": "^8.4.26",
+    "postcss-loader": "^7.3.3",
+    "postcss-preset-env": "^10.1.0",
+    "terser-webpack-plugin": "^5.3.9",
+    "tslib": "^2.6.0",
+    "url-loader": "^4.1.1",
+    "webpack": "^5.95.0",
+    "webpackbar": "^6.0.1"
+  },
+  "peerDependencies": {
+    "@docusaurus/faster": "*"
+  },
+  "peerDependenciesMeta": {
+    "@docusaurus/faster": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@total-typescript/shoehorn": "^0.1.2"
+  },
+  "engines": {
+    "node": ">=18.0"
+  }
+}

packages/docusaurus-bundler/src/compiler.ts

@@ -0,0 +1,87 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {type Configuration} from 'webpack';
+import logger from '@docusaurus/logger';
+import formatWebpackMessages from './legacy/formatWebpackMessages';
+import type webpack from 'webpack';
+import type {CurrentBundler} from '@docusaurus/types';
+
+export function formatStatsErrorMessage(
+  statsJson: ReturnType<webpack.Stats['toJson']> | undefined,
+): string | undefined {
+  if (statsJson?.errors?.length) {
+    // TODO formatWebpackMessages does not print stack-traces
+    // Also the error causal chain is lost here
+    // We log the stacktrace inside serverEntry.tsx for now (not ideal)
+    const {errors} = formatWebpackMessages(statsJson);
+    return errors
+      .map((str) => logger.red(str))
+      .join(`\n\n${logger.yellow('--------------------------')}\n\n`);
+  }
+  return undefined;
+}
+
+export function printStatsWarnings(
+  statsJson: ReturnType<webpack.Stats['toJson']> | undefined,
+): void {
+  if (statsJson?.warnings?.length) {
+    statsJson.warnings?.forEach((warning) => {
+      logger.warn(warning);
+    });
+  }
+}
+
+declare global {
+  interface Error {
+    /** @see https://webpack.js.org/api/node/#error-handling */
+    details?: unknown;
+  }
+}
+
+export function compile({
+  configs,
+  currentBundler,
+}: {
+  configs: Configuration[];
+  currentBundler: CurrentBundler;
+}): Promise<webpack.MultiStats> {
+  return new Promise((resolve, reject) => {
+    const compiler = currentBundler.instance(configs);
+    compiler.run((err, stats) => {
+      if (err) {
+        logger.error(err.stack ?? err);
+        if (err.details) {
+          logger.error(err.details);
+        }
+        reject(err);
+      }
+      // Let plugins consume all the stats
+      const errorsWarnings = stats?.toJson('errors-warnings');
+      if (stats?.hasErrors()) {
+        const statsErrorMessage = formatStatsErrorMessage(errorsWarnings);
+        reject(
+          new Error(
+            `Failed to compile due to Webpack errors.\n${statsErrorMessage}`,
+          ),
+        );
+      }
+      printStatsWarnings(errorsWarnings);
+
+      // Webpack 5 requires calling close() so that persistent caching works
+      // See https://github.com/webpack/webpack.js.org/pull/4775
+      compiler.close((errClose) => {
+        if (errClose) {
+          logger.error(`Error while closing Webpack compiler: ${errClose}`);
+          reject(errClose);
+        } else {
+          resolve(stats!);
+        }
+      });
+    });
+  });
+}

packages/docusaurus-bundler/src/currentBundler.ts

@@ -0,0 +1,106 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import webpack from 'webpack';
+import WebpackBar from 'webpackbar';
+import MiniCssExtractPlugin from 'mini-css-extract-plugin';
+import CopyWebpackPlugin from 'copy-webpack-plugin';
+import {importRspack} from './importFaster';
+import type {FasterModule} from './importFaster';
+import type {CurrentBundler, DocusaurusConfig} from '@docusaurus/types';
+
+// We inject a site config slice because the Rspack flag might change place
+type SiteConfigSlice = {
+  future: {
+    experimental_faster: Pick<
+      DocusaurusConfig['future']['experimental_faster'],
+      'rspackBundler'
+    >;
+  };
+};
+
+function isRspack(siteConfig: SiteConfigSlice): boolean {
+  return siteConfig.future.experimental_faster.rspackBundler;
+}
+
+export async function getCurrentBundler({
+  siteConfig,
+}: {
+  siteConfig: SiteConfigSlice;
+}): Promise<CurrentBundler> {
+  if (isRspack(siteConfig)) {
+    return {
+      name: 'rspack',
+      instance: (await importRspack()) as unknown as typeof webpack,
+    };
+  }
+  return {
+    name: 'webpack',
+    instance: webpack,
+  };
+}
+
+export function getCurrentBundlerAsRspack({
+  currentBundler,
+}: {
+  currentBundler: CurrentBundler;
+}): FasterModule['rspack'] {
+  if (currentBundler.name !== 'rspack') {
+    throw new Error(
+      `Can't getCurrentBundlerAsRspack() because current bundler is ${currentBundler.name}`,
+    );
+  }
+  return currentBundler.instance as unknown as FasterModule['rspack'];
+}
+
+export async function getCSSExtractPlugin({
+  currentBundler,
+}: {
+  currentBundler: CurrentBundler;
+}): Promise<typeof MiniCssExtractPlugin> {
+  if (currentBundler.name === 'rspack') {
+    // @ts-expect-error: this exists only in Rspack
+    return currentBundler.instance.CssExtractRspackPlugin;
+  }
+  return MiniCssExtractPlugin;
+}
+
+export async function getCopyPlugin({
+  currentBundler,
+}: {
+  currentBundler: CurrentBundler;
+}): Promise<typeof CopyWebpackPlugin> {
+  if (currentBundler.name === 'rspack') {
+    // @ts-expect-error: this exists only in Rspack
+    return currentBundler.instance.CopyRspackPlugin;
+  }
+  return CopyWebpackPlugin;
+}
+
+export async function getProgressBarPlugin({
+  currentBundler,
+}: {
+  currentBundler: CurrentBundler;
+}): Promise<typeof WebpackBar> {
+  if (currentBundler.name === 'rspack') {
+    const rspack = getCurrentBundlerAsRspack({currentBundler});
+    class CustomRspackProgressPlugin extends rspack.ProgressPlugin {
+      constructor({name, color = 'green'}: {name?: string; color?: string}) {
+        // Unfortunately rspack.ProgressPlugin does not have name/color options
+        // See https://rspack.dev/plugins/webpack/progress-plugin
+        super({
+          prefix: name,
+          template: `● {prefix:.bold} {bar:50.${color}/white.dim} ({percent}%) {wide_msg:.dim}`,
+          progressChars: '██',
+        });
+      }
+    }
+    return CustomRspackProgressPlugin as unknown as typeof WebpackBar;
+  }
+
+  return WebpackBar;
+}

packages/docusaurus-bundler/src/importFaster.ts

@@ -0,0 +1,77 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import logger from '@docusaurus/logger';
+import type {
+  MinimizerOptions as JsMinimizerOptions,
+  CustomOptions,
+} from 'terser-webpack-plugin';
+import type {MinimizerOptions as CssMinimizerOptions} from 'css-minimizer-webpack-plugin';
+
+export type FasterModule = Awaited<typeof import('@docusaurus/faster')>;
+
+async function importFaster(): Promise<FasterModule> {
+  return import('@docusaurus/faster');
+}
+
+async function ensureFaster(): Promise<FasterModule> {
+  try {
+    return await importFaster();
+  } catch (error) {
+    throw new Error(
+      `To enable Docusaurus Faster options, your site must add the ${logger.name(
+        '@docusaurus/faster',
+      )} package as a dependency.`,
+      {cause: error},
+    );
+  }
+}
+
+export async function importRspack(): Promise<FasterModule['rspack']> {
+  const faster = await ensureFaster();
+  return faster.rspack;
+}
+
+export async function importSwcLoader(): Promise<string> {
+  const faster = await ensureFaster();
+  return faster.swcLoader;
+}
+
+export async function importGetSwcLoaderOptions(): Promise<
+  FasterModule['getSwcLoaderOptions']
+> {
+  const faster = await ensureFaster();
+  return faster.getSwcLoaderOptions;
+}
+
+export async function importSwcJsMinimizerOptions(): Promise<
+  JsMinimizerOptions<CustomOptions>
+> {
+  const faster = await ensureFaster();
+  return faster.getSwcJsMinimizerOptions() as JsMinimizerOptions<CustomOptions>;
+}
+
+export async function importSwcHtmlMinifier(): Promise<
+  ReturnType<FasterModule['getSwcHtmlMinifier']>
+> {
+  const faster = await ensureFaster();
+  return faster.getSwcHtmlMinifier();
+}
+
+export async function importGetBrowserslistQueries(): Promise<
+  FasterModule['getBrowserslistQueries']
+> {
+  const faster = await ensureFaster();
+  return faster.getBrowserslistQueries;
+}
+
+export async function importLightningCssMinimizerOptions(): Promise<
+  CssMinimizerOptions<CustomOptions>
+> {
+  const faster = await ensureFaster();
+  return faster.getLightningCssMinimizerOptions() as CssMinimizerOptions<CustomOptions>;
+}

packages/docusaurus-bundler/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+export {printStatsWarnings, formatStatsErrorMessage, compile} from './compiler';
+
+export {
+  getCurrentBundler,
+  getCSSExtractPlugin,
+  getCopyPlugin,
+  getProgressBarPlugin,
+} from './currentBundler';
+
+export {getMinimizers} from './minification';
+export {
+  getHtmlMinifier,
+  type HtmlMinifier,
+  type HtmlMinifierType,
+} from './minifyHtml';
+export {createJsLoaderFactory} from './loaders/jsLoader';
+export {createStyleLoadersFactory} from './loaders/styleLoader';

packages/docusaurus-bundler/src/legacy/formatWebpackMessages.js

@@ -0,0 +1,138 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+// TODO Legacy CRA react-dev-utils package code
+//  This code was in CRA/react-dev-utils (deprecated in 2025)
+//  We just copied the code as-is to remove a fat/useless dependency subtree
+//  See https://github.com/facebook/docusaurus/pull/10956
+//  See https://github.com/facebook/create-react-app/blob/main/packages/react-dev-utils/formatWebpackMessages.js
+
+/* eslint-disable */
+
+const friendlySyntaxErrorLabel = 'Syntax error:';
+
+function isLikelyASyntaxError(message) {
+  return message.indexOf(friendlySyntaxErrorLabel) !== -1;
+}
+
+// Cleans up webpack error messages.
+function formatMessage(message) {
+  let lines = [];
+
+  if (typeof message === 'string') {
+    lines = message.split('\n');
+  } else if ('message' in message) {
+    lines = message['message'].split('\n');
+  } else if (Array.isArray(message)) {
+    message.forEach((message) => {
+      if ('message' in message) {
+        lines = message['message'].split('\n');
+      }
+    });
+  }
+
+  // Strip webpack-added headers off errors/warnings
+  // https://github.com/webpack/webpack/blob/master/lib/ModuleError.js
+  lines = lines.filter((line) => !/Module [A-z ]+\(from/.test(line));
+
+  // Transform parsing error into syntax error
+  // TODO: move this to our ESLint formatter?
+  lines = lines.map((line) => {
+    const parsingError = /Line (\d+):(?:(\d+):)?\s*Parsing error: (.+)$/.exec(
+      line,
+    );
+    if (!parsingError) {
+      return line;
+    }
+    const [, errorLine, errorColumn, errorMessage] = parsingError;
+    return `${friendlySyntaxErrorLabel} ${errorMessage} (${errorLine}:${errorColumn})`;
+  });
+
+  message = lines.join('\n');
+  // Smoosh syntax errors (commonly found in CSS)
+  message = message.replace(
+    /SyntaxError\s+\((\d+):(\d+)\)\s*(.+?)\n/g,
+    `${friendlySyntaxErrorLabel} $3 ($1:$2)\n`,
+  );
+  // Clean up export errors
+  message = message.replace(
+    /^.*export '(.+?)' was not found in '(.+?)'.*$/gm,
+    `Attempted import error: '$1' is not exported from '$2'.`,
+  );
+  message = message.replace(
+    /^.*export 'default' \(imported as '(.+?)'\) was not found in '(.+?)'.*$/gm,
+    `Attempted import error: '$2' does not contain a default export (imported as '$1').`,
+  );
+  message = message.replace(
+    /^.*export '(.+?)' \(imported as '(.+?)'\) was not found in '(.+?)'.*$/gm,
+    `Attempted import error: '$1' is not exported from '$3' (imported as '$2').`,
+  );
+  lines = message.split('\n');
+
+  // Remove leading newline
+  if (lines.length > 2 && lines[1].trim() === '') {
+    lines.splice(1, 1);
+  }
+  // Clean up file name
+  lines[0] = lines[0].replace(/^(.*) \d+:\d+-\d+$/, '$1');
+
+  // Cleans up verbose "module not found" messages for files and packages.
+  if (lines[1] && lines[1].indexOf('Module not found: ') === 0) {
+    lines = [
+      lines[0],
+      lines[1]
+        .replace('Error: ', '')
+        .replace('Module not found: Cannot find file:', 'Cannot find file:'),
+    ];
+  }
+
+  // Add helpful message for users trying to use Sass for the first time
+  if (lines[1] && lines[1].match(/Cannot find module.+sass/)) {
+    lines[1] = 'To import Sass files, you first need to install sass.\n';
+    lines[1] +=
+      'Run `npm install sass` or `yarn add sass` inside your workspace.';
+  }
+
+  message = lines.join('\n');
+  // Internal stacks are generally useless so we strip them... with the
+  // exception of stacks containing `webpack:` because they're normally
+  // from user code generated by webpack. For more information see
+  // https://github.com/facebook/create-react-app/pull/1050
+  message = message.replace(
+    /^\s*at\s((?!webpack:).)*:\d+:\d+[\s)]*(\n|$)/gm,
+    '',
+  ); // at ... ...:x:y
+  message = message.replace(/^\s*at\s<anonymous>(\n|$)/gm, ''); // at <anonymous>
+  lines = message.split('\n');
+
+  // Remove duplicated newlines
+  lines = lines.filter(
+    (line, index, arr) =>
+      index === 0 ||
+      line.trim() !== '' ||
+      line.trim() !== arr[index - 1].trim(),
+  );
+
+  // Reassemble the message
+  message = lines.join('\n');
+  return message.trim();
+}
+
+/**
+ * @param {import("webpack").Stats.ToJsonOutput} json.
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+module.exports = function formatWebpackMessages(json) {
+  const formattedErrors = json.errors.map(formatMessage);
+  const formattedWarnings = json.warnings.map(formatMessage);
+  const result = {errors: formattedErrors, warnings: formattedWarnings};
+  if (result.errors.some(isLikelyASyntaxError)) {
+    // If there are any syntax errors, show just them.
+    result.errors = result.errors.filter(isLikelyASyntaxError);
+  }
+  return result;
+};

packages/docusaurus-bundler/src/loaders/__tests__/jsLoader.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {fromPartial, type PartialDeep} from '@total-typescript/shoehorn';
+import {createJsLoaderFactory} from '../jsLoader';
+
+import type {RuleSetRule} from 'webpack';
+
+type SiteConfigSlice = Parameters<
+  typeof createJsLoaderFactory
+>[0]['siteConfig'];
+
+describe('createJsLoaderFactory', () => {
+  function testJsLoaderFactory(siteConfig?: {
+    webpack?: SiteConfigSlice['webpack'];
+    future?: PartialDeep<SiteConfigSlice['future']>;
+  }) {
+    return createJsLoaderFactory({
+      siteConfig: {
+        ...siteConfig,
+        webpack: siteConfig?.webpack,
+        future: fromPartial({
+          ...siteConfig?.future,
+          experimental_faster: fromPartial({
+            ...siteConfig?.future?.experimental_faster,
+          }),
+        }),
+      },
+    });
+  }
+
+  it('createJsLoaderFactory defaults to babel loader', async () => {
+    const createJsLoader = await testJsLoaderFactory();
+    expect(createJsLoader({isServer: true}).loader).toBe(
+      require.resolve('babel-loader'),
+    );
+    expect(createJsLoader({isServer: false}).loader).toBe(
+      require.resolve('babel-loader'),
+    );
+  });
+
+  it('createJsLoaderFactory accepts babel loader preset', async () => {
+    const createJsLoader = await testJsLoaderFactory({
+      webpack: {jsLoader: 'babel'},
+    });
+    expect(createJsLoader({isServer: true}).loader).toBe(
+      require.resolve('babel-loader'),
+    );
+    expect(createJsLoader({isServer: false}).loader).toBe(
+      require.resolve('babel-loader'),
+    );
+  });
+
+  it('createJsLoaderFactory accepts custom loader', async () => {
+    const createJsLoader = await testJsLoaderFactory({
+      webpack: {
+        jsLoader: (isServer) => {
+          return {loader: `my-loader-${isServer ? 'server' : 'client'}`};
+        },
+      },
+    });
+    expect(createJsLoader({isServer: true}).loader).toBe('my-loader-server');
+    expect(createJsLoader({isServer: false}).loader).toBe('my-loader-client');
+  });
+
+  it('createJsLoaderFactory rejects custom loader when using faster swc loader', async () => {
+    await expect(() =>
+      testJsLoaderFactory({
+        future: {
+          experimental_faster: {
+            swcJsLoader: true,
+          },
+        },
+        webpack: {
+          jsLoader: (isServer) => {
+            return {loader: `my-loader-${isServer ? 'server' : 'client'}`};
+          },
+        },
+      }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(`
+      "You can't use siteConfig.webpack.jsLoader and siteConfig.future.experimental_faster.swcJsLoader at the same time.
+      To avoid any configuration ambiguity, you must make an explicit choice:
+      - If you want to use Docusaurus Faster and SWC (recommended), remove siteConfig.webpack.jsLoader
+      - If you want to use a custom JS loader, use siteConfig.future.experimental_faster.swcJsLoader: false"
+    `);
+  });
+
+  it('createJsLoaderFactory accepts loaders with preset', async () => {
+    const createJsLoader = await testJsLoaderFactory({
+      webpack: {jsLoader: 'babel'},
+    });
+
+    expect(
+      createJsLoader({
+        isServer: true,
+      }).loader,
+    ).toBe(require.resolve('babel-loader'));
+    expect(
+      createJsLoader({
+        isServer: false,
+      }).loader,
+    ).toBe(require.resolve('babel-loader'));
+  });
+
+  it('createJsLoaderFactory allows customization', async () => {
+    const customJSLoader = (isServer: boolean): RuleSetRule => ({
+      loader: 'my-fast-js-loader',
+      options: String(isServer),
+    });
+
+    const createJsLoader = await testJsLoaderFactory({
+      webpack: {jsLoader: customJSLoader},
+    });
+
+    expect(
+      createJsLoader({
+        isServer: true,
+      }),
+    ).toEqual(customJSLoader(true));
+    expect(
+      createJsLoader({
+        isServer: false,
+      }),
+    ).toEqual(customJSLoader(false));
+  });
+});

packages/docusaurus-bundler/src/loaders/jsLoader.ts

@@ -0,0 +1,87 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {getBabelOptions} from '@docusaurus/babel';
+import {importSwcLoader, importGetSwcLoaderOptions} from '../importFaster';
+import {getCurrentBundler} from '../currentBundler';
+import type {ConfigureWebpackUtils, DocusaurusConfig} from '@docusaurus/types';
+
+const BabelJsLoaderFactory: ConfigureWebpackUtils['getJSLoader'] = ({
+  isServer,
+  babelOptions,
+}) => {
+  return {
+    loader: require.resolve('babel-loader'),
+    options: getBabelOptions({isServer, babelOptions}),
+  };
+};
+
+async function createSwcJsLoaderFactory(): Promise<
+  ConfigureWebpackUtils['getJSLoader']
+> {
+  const loader = await importSwcLoader();
+  const getOptions = await importGetSwcLoaderOptions();
+  return ({isServer}) => {
+    return {
+      loader,
+      options: getOptions({isServer}),
+    };
+  };
+}
+
+// Same as swcLoader, except we use the built-in SWC loader
+async function createRspackSwcJsLoaderFactory(): Promise<
+  ConfigureWebpackUtils['getJSLoader']
+> {
+  const loader = 'builtin:swc-loader';
+  const getOptions = await importGetSwcLoaderOptions();
+  return ({isServer}) => {
+    return {
+      loader,
+      options: getOptions({isServer}),
+    };
+  };
+}
+
+// Confusing: function that creates a function that creates actual js loaders
+// This is done on purpose because the js loader factory is a public API
+// It is injected in configureWebpack plugin lifecycle for plugin authors
+export async function createJsLoaderFactory({
+  siteConfig,
+}: {
+  siteConfig: {
+    webpack?: DocusaurusConfig['webpack'];
+    future: {
+      experimental_faster: DocusaurusConfig['future']['experimental_faster'];
+    };
+  };
+}): Promise<ConfigureWebpackUtils['getJSLoader']> {
+  const currentBundler = await getCurrentBundler({siteConfig});
+  const isSWCLoader = siteConfig.future.experimental_faster.swcJsLoader;
+  if (isSWCLoader) {
+    if (siteConfig.webpack?.jsLoader) {
+      throw new Error(
+        `You can't use siteConfig.webpack.jsLoader and siteConfig.future.experimental_faster.swcJsLoader at the same time.
+To avoid any configuration ambiguity, you must make an explicit choice:
+- If you want to use Docusaurus Faster and SWC (recommended), remove siteConfig.webpack.jsLoader
+- If you want to use a custom JS loader, use siteConfig.future.experimental_faster.swcJsLoader: false`,
+      );
+    }
+    return currentBundler.name === 'rspack'
+      ? createRspackSwcJsLoaderFactory()
+      : createSwcJsLoaderFactory();
+  }
+
+  const jsLoader = siteConfig.webpack?.jsLoader ?? 'babel';
+  if (jsLoader instanceof Function) {
+    return ({isServer}) => jsLoader(isServer);
+  }
+  if (jsLoader === 'babel') {
+    return BabelJsLoaderFactory;
+  }
+  throw new Error(`Docusaurus bug: unexpected jsLoader value${jsLoader}`);
+}