Skip to main content

Experimental Faster Build — Working Report

Upgrade Date: 2026-02-17
Docusaurus Version: v3.9.2
Site: brain.id86.net
Total Docs at Time of Upgrade: 1,113 files (994 .mdx + 119 .md)
Official Source: Docusaurus 3.8 Release Blog — Performance
Status: ✅ Successfully Installed and Verified

1. What Was Done​

Enabled the experimental_faster feature on the production Docusaurus site (brain.id86.net). This replaces the default JavaScript-based build toolchain with Rust-based alternatives for significantly faster builds.

Tools Replaced​

Build StepBefore (Default)After (experimental_faster)
BundlerWebpack (JavaScript)Rspack (Rust)
JS TranspilerBabel (JavaScript)SWC (Rust)
JS MinifierTerser (JavaScript)SWC (Rust)
HTML Minifierhtml-minifier-terserSWC (Rust)
CSS Minifiercssnano / PostCSSLightning CSS (Rust)
Static GenerationSingle-threadedWorker Threads (multi-core)
Build CacheWebpack persistent cacheRspack persistent cache

Flags Enabled​

Setting experimental_faster: true enables all of the following flags at once:

FlagDescription
swcJsLoaderSWC replaces Babel for JS/TS transpilation
swcJsMinimizerSWC replaces Terser for JS minification
swcHtmlMinimizerSWC replaces html-minifier-terser for HTML minification
lightningCssMinimizerLightning CSS replaces cssnano for CSS minification
rspackBundlerRspack replaces Webpack as the bundler
rspackPersistentCacheRspack caches build results for faster rebuilds
ssgWorkerThreadsStatic site generation uses Node.js Worker Threads across CPU cores

The v4.removeLegacyPostBuildHeadAttribute future flag was also enabled as it is required for ssgWorkerThreads to function.

2. Exact Changes Made​

2.1 Package Installation​

Installed @docusaurus/faster inside the Docker container:

sudo docker exec -w /app docusaurus sh -c "npm install @docusaurus/faster"

Result: 26 packages added. The package resolved to version ^3.9.2 (matching the existing Docusaurus version).

2.2 package.json Diff​

The only change to package.json was the addition of the @docusaurus/faster dependency:

 "dependencies": {
   "@docusaurus/core": "latest",
+  "@docusaurus/faster": "^3.9.2",
   "@docusaurus/preset-classic": "latest",
   "@docusaurus/theme-mermaid": "^3.9.2",
   "@easyops-cn/docusaurus-search-local": "0.55.0",
   "clsx": "latest",
   "open-ask-ai": "^0.7.3",
   "prism-react-renderer": "latest",
   "react": "latest",
   "react-dom": "latest"
 }

2.3 docusaurus.config.js Diff​

Added the future configuration block after the favicon line and before the i18n block:

   favicon: 'img/favicon.ico',

+  // ─── Experimental Faster Build (Rspack + SWC + Lightning CSS) ───
+  // Installed: 2026-02-17 | Source: https://docusaurus.io/blog/releases/3.8
+  // Backup: .backup-experimental-faster/
+  future: {
+    v4: {
+      removeLegacyPostBuildHeadAttribute: true,
+    },
+    experimental_faster: true,
+  },
+
   i18n: {
     defaultLocale: 'en',
     locales: ['en'],
   },

Location in file: Lines 17–27 of the updated docusaurus.config.js.

2.4 Full future Block Reference​

// docusaurus.config.js
const config = {
  // ... existing config ...

  future: {
    v4: {
      removeLegacyPostBuildHeadAttribute: true,
    },
    experimental_faster: true,
  },

  // ... rest of config ...
};

3. Build Results​

3.1 First Build (Cold — No Persistent Cache)​

Build command: sudo docker exec -w /app docusaurus sh -c "npm run build"
Build time:   111 seconds (1 minute 51 seconds)
Build output: /app/build/index.html — EXISTS ✓
Exit code:    0

3.2 Build Warnings Observed​

The following non-critical warnings appeared during the build:

WarningSeverityAction Needed
siteConfig.onBrokenMarkdownLinks is deprecatedLowMigrate to siteConfig.markdown.hooks.onBrokenMarkdownLinks in future
Blog author not defined in authors.ymlLowDefine author in authors.yml or set onInlineAuthors: 'ignore'
experiments.lazyBarrel deprecated in Rspack v2.0InfoNo action — Docusaurus will update internally
Unused Markdown directive in speed-test.mdxLowFix :contentReference directive in that file
HTML minifier diagnostic in speed-test.mdxLowFix nested <p> tags in that file

None of these warnings caused build failure. They are pre-existing issues unrelated to experimental_faster.

3.3 Rspack Confirmation​

The build output included this line, confirming Rspack is active:

[Rspack Deprecation] `experiments.lazyBarrel` config is deprecated and will be 
removed in Rspack v2.0. Lazy barrel is already stable and enabled by default. 
Remove this option from your Rspack configuration.

This message only appears when Rspack is the active bundler, confirming the upgrade was successful.

3.4 Post-Build Actions​

# Container restart
sudo docker restart docusaurus

# Site verification
curl -s -o /dev/null -w "HTTP Status: %{http_code}" https://brain.id86.net
# Result: HTTP Status: 302 (redirect to docs — expected behavior)

4. Backup Location​

All original files were backed up before any changes were made:

/opt/docker-data/apps/docusaurus/site/.backup-experimental-faster/
├── docusaurus.config.js.bak     (13,801 bytes — original config)
├── package.json.bak             (948 bytes — original dependencies)
└── package-lock.json.bak        (783,112 bytes — original lock file)

Backup timestamp: 2026-02-17 08:57:29 UTC

5. Rollback Procedure​

If experimental_faster causes issues in the future, follow this rollback procedure:

Quick Rollback (Full — Remove Everything)​

# 1. Restore original config
cp /opt/docker-data/apps/docusaurus/site/.backup-experimental-faster/docusaurus.config.js.bak \
   /opt/docker-data/apps/docusaurus/site/docusaurus.config.js

# 2. Restore original package.json
cp /opt/docker-data/apps/docusaurus/site/.backup-experimental-faster/package.json.bak \
   /opt/docker-data/apps/docusaurus/site/package.json

# 3. Restore original package-lock.json
cp /opt/docker-data/apps/docusaurus/site/.backup-experimental-faster/package-lock.json.bak \
   /opt/docker-data/apps/docusaurus/site/package-lock.json

# 4. Reinstall original dependencies (inside container)
sudo docker exec -w /app docusaurus sh -c "npm ci"

# 5. Rebuild
sudo docker exec -w /app docusaurus sh -c "npm run build"

# 6. Restart
sudo docker restart docusaurus

Partial Rollback (Config Only — Keep Package Installed)​

If you want to disable experimental_faster without uninstalling the package:

# Remove ONLY the future block from docusaurus.config.js
# Delete these lines:
#   future: {
#     v4: {
#       removeLegacyPostBuildHeadAttribute: true,
#     },
#     experimental_faster: true,
#   },

# Then rebuild
sudo docker exec -w /app docusaurus sh -c "npm run build"
sudo docker restart docusaurus

Selective Flag Rollback (Disable Only Problematic Flags)​

If only one specific flag causes issues:

future: {
  v4: {
    removeLegacyPostBuildHeadAttribute: true,
  },
  experimental_faster: {
    swcJsLoader: true,
    swcJsMinimizer: true,
    swcHtmlMinimizer: true,
    lightningCssMinimizer: true,
    rspackBundler: true,
    rspackPersistentCache: true,
    ssgWorkerThreads: false,    // ← disable only the problematic flag
  },
},

6. File Inventory​

Files Modified​

FileChange
/opt/docker-data/apps/docusaurus/site/docusaurus.config.jsAdded future block with experimental_faster: true
/opt/docker-data/apps/docusaurus/site/package.jsonAdded @docusaurus/faster: ^3.9.2 dependency
/opt/docker-data/apps/docusaurus/site/package-lock.jsonUpdated by npm install (26 new packages)

Files Created​

FilePurpose
/opt/docker-data/apps/docusaurus/site/.backup-experimental-faster/docusaurus.config.js.bakBackup of original config
/opt/docker-data/apps/docusaurus/site/.backup-experimental-faster/package.json.bakBackup of original package.json
/opt/docker-data/apps/docusaurus/site/.backup-experimental-faster/package-lock.json.bakBackup of original lock file

7. Current docusaurus.config.js — future Block​

This is the exact block that was added to the config. For AI agents: do not modify or remove this block unless explicitly instructed by the user:

  // ─── Experimental Faster Build (Rspack + SWC + Lightning CSS) ───
  // Installed: 2026-02-17 | Source: https://docusaurus.io/blog/releases/3.8
  // Backup: .backup-experimental-faster/
  future: {
    v4: {
      removeLegacyPostBuildHeadAttribute: true,
    },
    experimental_faster: true,
  },

8. Current package.json — Full Contents​

{
  "name": "docusaurus-site",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "start": "docusaurus build && docusaurus serve --host 0.0.0.0 --port 3000",
    "prod": "docusaurus serve --host 0.0.0.0 --port 3000",
    "dev": "docusaurus start --host 0.0.0.0 --port 3000",
    "build": "docusaurus build",
    "serve": "docusaurus serve --host 0.0.0.0 --port 3000"
  },
  "dependencies": {
    "@docusaurus/core": "latest",
    "@docusaurus/faster": "^3.9.2",
    "@docusaurus/preset-classic": "latest",
    "@docusaurus/theme-mermaid": "^3.9.2",
    "@easyops-cn/docusaurus-search-local": "0.55.0",
    "clsx": "latest",
    "open-ask-ai": "^0.7.3",
    "prism-react-renderer": "latest",
    "react": "latest",
    "react-dom": "latest"
  },
  "browserslist": {
    "production": [">0.5%", "not dead", "not op_mini all"],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}

9. Expected Performance at Scale​

Based on official benchmarks from the Docusaurus 3.8 release and the React Native website (~2,000 pages):

ScaleWithout experimental_fasterWith experimental_faster (Cold)With experimental_faster (Rebuild / Cached)
1,113 docs (current)~3–5 min111 sec (measured)~40–60 sec (estimated)
5,000 docs~10–20 min~5–8 min~2–4 min
10,000 docs~20–40 min~8–15 min~4–8 min

How Persistent Cache Works​

  • First build (cold): full build, creates cache in ./node_modules/.cache
  • Subsequent builds (warm): Rspack reuses cached results, 2–5× faster
  • Cache invalidation: only changed files are reprocessed
  • Requirement: ./node_modules/.cache must persist between builds

Additional Optimization Available​

Disabling concatenateModule can further improve build times for large sites:

"It only saves 3% JS, and for a very large site, this change was incredibly impactful: 4× faster on cold builds, 16× faster rebuilds." — Docusaurus Discussion #11199

This optimization has not been applied yet but should be considered when scaling to 5,000+ docs.

10. Plugin Compatibility​

The following plugins are installed on this site and were tested with experimental_faster:

PluginVersionCompatibleNotes
@docusaurus/preset-classiclatest✅ YesOfficial plugin, fully supported
@docusaurus/theme-mermaid^3.9.2✅ YesMermaid diagrams render correctly
@easyops-cn/docusaurus-search-local0.55.0✅ YesLocal search works after build
prism-react-rendererlatest✅ YesSyntax highlighting works
open-ask-ai^0.7.3✅ YesNo issues observed

11. Infrastructure Context​

Docker Setup​

PropertyValue
Container namedocusaurus
Working directory/app
Build commandnpm run build (docusaurus build)
Serve commanddocusaurus serve --host 0.0.0.0 --port 3000
Start commanddocusaurus build && docusaurus serve
Build triggerbuild-if-changed.sh (cron or manual)

Build Trigger Script​

The site uses build-if-changed.sh to detect file changes before triggering builds. This script is compatible with experimental_faster — no changes needed.

The script:

  1. Hashes watched files (docs, config, src)
  2. Compares with previous hash
  3. Only triggers npm run build if files changed
  4. Validates build/index.html exists after build
  5. Restarts the Docker container

12. AI Agent Instructions​

For Future AI Agents Working on This Site​

  1. Do not remove the future block from docusaurus.config.js unless explicitly asked
  2. Do not uninstall @docusaurus/faster unless explicitly asked
  3. The site uses Rspack (not Webpack) — keep this in mind when debugging build issues
  4. Build warnings about lazyBarrel and onBrokenMarkdownLinks are pre-existing and unrelated to experimental_faster
  5. If a build fails after a content change, the issue is likely in the content (MDX syntax), not in experimental_faster
  6. Backup files are at .backup-experimental-faster/ — use these for rollback if needed
  7. The persistent cache is stored in ./node_modules/.cache — do not delete this folder unless you want a full cold rebuild

Verifying experimental_faster Is Active​

Check for this in build output:

[Rspack Deprecation] `experiments.lazyBarrel` config is deprecated...

If this message appears, Rspack is the active bundler and experimental_faster is working.

Build Time Monitoring​

# Measure build time
START=$(date +%s)
sudo docker exec -w /app docusaurus sh -c "npm run build"
END=$(date +%s)
echo "Build time: $((END - START)) seconds"
ResourceURL
Official Blog (v3.8)docusaurus.io/blog/releases/3.8
@docusaurus/faster Packagedocusaurus.io/docs/api/misc/@docusaurus/faster
Future Config APIdocusaurus.io/docs/api/docusaurus-config#future
Tracking Issuegithub.com/facebook/docusaurus/issues/10556
Persistent Cache PRgithub.com/facebook/docusaurus/pull/10931
Worker Threads PRgithub.com/facebook/docusaurus/pull/10826
concatenateModule Optimizationgithub.com/facebook/docusaurus/discussions/11199
Build Script Repogithub.com/donnyaw/docusaurus-build-if-changed