Upgrade Docusaurus - Enable Docusaurus Faster on website #468
Conversation
WalkthroughThis pull request includes updates to several configuration files in the project. The Changes
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
❌ Deploy Preview for easyops-cn-docusaurus-search-local failed.
|
|
👍 Great work! I got no idea why it doesn't work with yarn PnP, either. Though using node modules linker works, right? Maybe related to dependencies with canary versions. |
|
I'll try again once v3.6 is out and we'll see For now it's already nice to have a POC proving that this plugin works with the new bundler :) |
|
Docusaurus v3.6 is out: https://docusaurus.io/blog/releases/3.6 PR ready to review (but still fighting with PnP issues) Unfortunately, the Yarn PnP error remains, and it only builds with node linker. Maybe @arcanis any idea what could cause this error? Edit, it seems using |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Outside diff range and nitpick comments (3)
.yarnrc.yml (2)
8-9: LGTM! Consider adding a comment about this being temporary.Setting
nodeLinker: node-modulesis a good temporary solution to bypass the Yarn PnP issues mentioned in the PR.Consider adding a comment above this line to document that this is a temporary workaround:
+# Temporary: Using node-modules instead of PnP due to Rspack compatibility issues nodeLinker: node-modules
11-14: Consider using a more specific version constraint.Using
"*"as the version constraint for@docusaurus/fastermight lead to unexpected behavior if incompatible versions are released.Consider using a more specific version range that matches your Docusaurus version:
"@docusaurus/bundler@*": dependencies: - "@docusaurus/faster": "*" + "@docusaurus/faster": "^3.6.0"website/package.json (1)
15-19: Consider using caret ranges for version specificationsUsing exact versions (
3.6.0) instead of caret ranges (^3.6.0) might make future minor updates more difficult to manage. Consider using caret ranges unless there's a specific reason for exact versions.- "@docusaurus/core": "3.6.0", - "@docusaurus/faster": "3.6.0", - "@docusaurus/preset-classic": "3.6.0", - "@docusaurus/theme-classic": "3.6.0", - "@docusaurus/theme-common": "3.6.0", + "@docusaurus/core": "^3.6.0", + "@docusaurus/faster": "^3.6.0", + "@docusaurus/preset-classic": "^3.6.0", + "@docusaurus/theme-classic": "^3.6.0", + "@docusaurus/theme-common": "^3.6.0",
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
⛔ Files ignored due to path filters (1)
yarn.lockis excluded by!**/yarn.lock,!**/*.lock
📒 Files selected for processing (5)
.gitignore(1 hunks).yarnrc.yml(1 hunks)package.json(1 hunks)website/docusaurus.config.js(1 hunks)website/package.json(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- .gitignore
🔇 Additional comments (3)
website/package.json (1)
9-9: LGTM: Added useful cache clearing script
The addition of the "clear" script is beneficial for testing and benchmarking the new Docusaurus Faster bundler.
package.json (2)
50-55: LGTM! Consistent version updates across all Docusaurus packages.
Good practice maintaining version consistency by updating all Docusaurus packages to exactly 3.6.0 in resolutions.
50-55: Monitor PnP compatibility with Docusaurus 3.6.0.
Since you're experiencing Yarn PnP issues, consider:
- Testing the build with nodeLinker: node-modules temporarily
- Tracking the issue in Docusaurus repository
Let's verify if there are any known PnP issues:
| "@docusaurus/core": "3.6.0", | ||
| "@docusaurus/faster": "3.6.0", | ||
| "@docusaurus/preset-classic": "3.6.0", | ||
| "@docusaurus/theme-classic": "3.6.0", | ||
| "@docusaurus/theme-common": "3.6.0", |
There was a problem hiding this comment.
💡 Codebase verification
Inconsistent Docusaurus dependency versions detected across packages
The verification reveals version inconsistencies across different packages in the repository:
website/package.json: Fixed version3.6.0website-multi-docs/package.json: Caret range^3.0.0docusaurus-search-local/package.json: Wide range^2 || ^3
These inconsistencies could lead to compatibility issues. Consider:
- Aligning versions in
website-multi-docsto use the same fixed version3.6.0 - Updating
docusaurus-search-localto specifically target version 3
🔗 Analysis chain
Verify dependency version consistency
Let's verify that all Docusaurus-related dependencies are consistently updated across the project to avoid version conflicts.
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Description: Check for inconsistent @docusaurus/* package versions across package.json files
# Find all package.json files
echo "Searching for @docusaurus/* dependencies in all package.json files:"
fd package.json --type f --exec sh -c '
echo "\nChecking {}"
cat {} | jq -r "
if has(\"dependencies\") then
.dependencies | to_entries[] |
select(.key | startswith(\"@docusaurus/\")) |
\"\(.key): \(.value)\"
else
empty
end
"
'
Length of output: 1111
website/docusaurus.config.js
Outdated
| future: { | ||
| experimental_faster: true, | ||
| }, |
There was a problem hiding this comment.
💡 Codebase verification
Add documentation for experimental feature and its implications
The experimental feature is correctly configured and the required dependencies (@docusaurus/core and @docusaurus/faster v3.6.0) are properly installed. However, since there's no existing documentation about this experimental feature in the codebase, it's important to document its usage and implications.
const buildType = process.env.BUILD_TYPE;
module.exports = {
+ // Enable Docusaurus Faster (using @docusaurus/faster v3.6.0)
+ // This experimental feature uses Rspack instead of Webpack for improved build performance
+ // Note: If you experience issues with Yarn PnP, you may need to disable this feature
future: {
experimental_faster: true,
},🔗 Analysis chain
Document experimental feature and known limitations.
The experimental feature is correctly configured under the future namespace. However, given its experimental status and known limitations with Yarn PnP, consider adding comments to document:
- The significant performance improvements for cold builds
- Current limitations with Yarn PnP
- Minimum required Docusaurus version (3.6.0)
Add documentation comments above the configuration:
const buildType = process.env.BUILD_TYPE;
module.exports = {
+ // Enable Docusaurus Faster for improved build performance
+ // Note: Requires Docusaurus >= 3.6.0
+ // - Cold builds: ~3.1s (vs ~11.8s without)
+ // - Known issue: Build fails with Yarn PnP enabled
future: {
experimental_faster: true,
},Let's verify if this experimental feature is documented in Docusaurus:
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Search for documentation about the experimental_faster feature
rg -i "experimental[_\s]faster|docusaurus faster" README.md docs/
Length of output: 113
Script:
#!/bin/bash
# Let's first check if we're in the correct directory structure
fd -t d "website"
# Then search for any documentation about the experimental feature
cd website && rg -i "experimental[_\s]faster|docusaurus faster" .
# Also check package.json for Docusaurus version
cat website/package.json | jq '.dependencies["@docusaurus/core"], .dependencies["@docusaurus/faster"]'
Length of output: 325
Script:
#!/bin/bash
# Let's check package.json in the correct location
cat package.json | jq '.dependencies'
# Also search for any related documentation in the website directory
rg -i "performance|build.*speed|faster" . -g "!node_modules" -g "!build" -A 2 -B 2
Length of output: 6305
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
⛔ Files ignored due to path filters (1)
yarn.lockis excluded by!**/yarn.lock,!**/*.lock
📒 Files selected for processing (6)
.yarnrc.yml(1 hunks)website-multi-docs/babel.config.js(0 hunks)website-multi-docs/docusaurus.config.js(1 hunks)website-multi-docs/package.json(2 hunks)website/babel.config.js(0 hunks)website/docusaurus.config.js(1 hunks)
💤 Files with no reviewable changes (2)
- website-multi-docs/babel.config.js
- website/babel.config.js
🚧 Files skipped from review as they are similar to previous changes (2)
- .yarnrc.yml
- website/docusaurus.config.js
🔇 Additional comments (3)
website-multi-docs/package.json (1)
18-18: Addition of @docusaurus/faster package noted with PnP compatibility caveat.
The addition of @docusaurus/faster aligns with the PR's objective to enable Docusaurus Faster bundler. However, be aware of the known Yarn PnP compatibility issues mentioned in the PR description.
Let's check for any PnP-related configurations that might affect this package:
#!/bin/bash
# Description: Check for PnP-related configurations
# Expected: Identify any PnP settings that might affect @docusaurus/faster
echo "Checking for PnP-related configurations..."
fd "\.yarnrc\.yml$|\.pnp\..*\.js$" --type fwebsite-multi-docs/docusaurus.config.js (2)
9-18: Verify compatibility with search plugin and multi-docs setup.
The experimental faster configuration is being used alongside the local search plugin and multiple docs plugins. While the optimization choices look good, we should verify compatibility:
-
Search Plugin Integration:
- Ensure search indexing works correctly with faster builds
- Verify search context paths are properly processed
-
Multi-docs Performance:
- Monitor build times for both product and community docs
- Verify that caching benefits apply across all doc types
Let's check for any known compatibility issues:
#!/bin/bash
# Description: Check for compatibility issues between search plugin and faster builds
# Search for any reported issues with @easyops-cn/docusaurus-search-local and faster builds
rg -i "docusaurus.*faster.*search|search.*faster" .github/
rg -i "docusaurus.*faster.*search|search.*faster" docs/
# Check if search plugin is used in other Docusaurus faster implementations
rg -i "@easyops-cn/docusaurus-search-local.*experimental_faster" Consider implementing gradual rollout:
- Test search functionality thoroughly in a staging environment
- Monitor search indexing performance with the new build system
- Consider adding build-time checks for search index generation
Also applies to: 134-162
9-18: Verify experimental configuration alignment with requirements.
The experimental faster configuration looks well-structured, with appropriate optimization choices:
- SWC-based optimizations for JS and HTML are enabled
- Lightning CSS minimizer is enabled for CSS optimization
- MDX cross-compiler cache is enabled for better build performance
- Rspack bundler is correctly disabled due to known PnP compatibility issues
Let's verify the Docusaurus version compatibility:
Consider the following recommendations:
- Monitor build performance metrics to validate the optimization benefits
- Keep track of the Rspack bundler compatibility status for future enablement
- Consider adding error monitoring for experimental features in production
✅ Verification successful
Experimental faster configuration is correctly implemented and compatible
The verification confirms that:
- Docusaurus v3.6.0 is being used, which fully supports the experimental faster features
@docusaurus/fasterpackage is correctly installed as a dependency- The configuration is properly implemented alongside the local search plugin (@easyops-cn/docusaurus-search-local)
- All optimization flags are appropriately set, with rspack bundler disabled as intended
The experimental configuration is well-aligned with the project requirements and should provide the expected build performance improvements while maintaining compatibility with the search functionality.
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Description: Verify Docusaurus version and dependencies
# Expected: Version 3.6.0 or higher
# Check package.json for @docusaurus/core version
cat package.json | jq -r '.dependencies["@docusaurus/core"] // .devDependencies["@docusaurus/core"]'
# Check if @docusaurus/faster is installed
cat package.json | jq -r '.dependencies["@docusaurus/faster"] // .devDependencies["@docusaurus/faster"]'
Length of output: 231
Script:
#!/bin/bash
# Let's try a different approach to verify the package.json content
fd package.json --type f --exec cat {} \; | grep -A 10 -B 10 "@docusaurus"
# Also check for any docusaurus config files to understand the setup better
fd docusaurus.config.js --type f --exec cat {} \;
# Check if there are any yarn/npm lock files to verify dependencies
fd "yarn.lock|package-lock.json" --type f --max-depth 2 --exec head -n 50 {} \;
Length of output: 14717
| "@docusaurus/preset-classic": "^3.0.0", | ||
| "@docusaurus/theme-classic": "^3.0.0", | ||
| "@docusaurus/theme-common": "^3.0.0", | ||
| "@docusaurus/core": "3.6.0", |
There was a problem hiding this comment.
💡 Codebase verification
Version consistency verified across website and website-multi-docs, but other packages need attention
The verification revealed mixed versioning patterns across the repository:
websiteandwebsite-multi-docscorrectly use exact version 3.6.0 for all Docusaurus packagesdocusaurus-search-localpackage uses different version patterns:- Uses
^2 || ^3for some packages - Uses
^3.0.0for others - Uses exact version
3.0.0for@docusaurus/tsconfig
- Uses
This inconsistency in versioning patterns across the repository could lead to compatibility issues. Consider aligning all Docusaurus package versions to 3.6.0 across the entire repository for better consistency.
🔗 Analysis chain
LGTM! Consistent version updates across Docusaurus packages.
The alignment of all Docusaurus packages to exact version 3.6.0 (removing caret versioning) ensures build consistency, which is crucial for testing the new bundler.
Let's verify version consistency across all Docusaurus packages in the repository:
Also applies to: 19-22, 31-31
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Description: Check for any mismatched Docusaurus package versions
# Expected: All Docusaurus packages should be at version 3.6.0
echo "Checking Docusaurus package versions across all package.json files..."
fd package.json --type f --exec jq -r '.dependencies + .devDependencies | with_entries(select(.key | startswith("@docusaurus"))) | to_entries[] | "\(.key): \(.value)"'
Length of output: 367
Script:
#!/bin/bash
# Let's try a different approach to check package versions
# First, let's confirm the existence of package.json files
fd package.json --type f
# Then let's examine their content specifically for Docusaurus packages
echo "=== Checking Docusaurus package versions ==="
fd package.json --type f --exec cat {} \; | grep "@docusaurus.*\":" -A 1
# Additionally, let's check if there are any workspace configurations
echo "=== Checking for workspace configurations ==="
fd "package.json|yarn.lock|pnpm-workspace.yaml|lerna.json" --type f --max-depth 1
Length of output: 1977
Docusaurus maintainer here 👋
This is a POC to ensure this plugin is compatible with Docusaurus Faster
I'm not sure how your setup works exactly, not super familiar with Yarn PnP but got some annoying errors due to it 😅
I'm able to build with Webpack, but Rspack fails with this error I can't solve when PnP is enabled:
And idea?
Benchmark
Using node modules linker
Cold builds - much faster
Warm builds - same:
Summary by CodeRabbit
New Features
Updates
@docusaurus/faster.Configuration Changes
.gitignoreto exclude.ideadirectory.