Repository navigation
feat: create @docusaurus/fs package with fs-extra compatible helpers (AI-assisted) - #12560
Merged
Merged
Conversation
2 of 3 tasks
✅ [V2]
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Size Change: 0 B Total Size: 12.4 MB ℹ️ View Unchanged
|
⚡️ Lighthouse report for the deploy preview of this PR
|
|
Size Change: 0 B Total Size: 12.6 MB ℹ️ View Unchanged
|
2 of 3 tasks
slorber
added
the
pr: ignore
slorber
force-pushed
the
slorber/fs-utils
branch
from
October 2, 2026 10:52
ca1c855 to
d0a12fe
Compare
2 of 3 tasks
slorber
force-pushed
the
slorber/fs-utils
branch
from
October 2, 2026 11:25
d0a12fe to
b98199f
Compare
…(AI-assisted) New package isolating the file system operations of Docusaurus. Add pathExists, outputFile, readJSON and realpath helpers, with the same semantics as their fs-extra counterparts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
slorber
force-pushed
the
slorber/fs-utils
branch
from
October 8, 2026 15:52
b98199f to
2cdf371
Compare
slorber
changed the title
This was referenced Oct 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pre-flight checklist
Motivation
Create a new
@docusaurus/fspackage to isolate the file system operations of Docusaurus. We do a lot of FS operations, and having them in a dedicated package will let us make all of them go through it later, and implement further optimizations in a single place.First step to remove
fs-extra: the package starts with the few helpers we need, with the same semantics as their fs-extra counterparts, so that the PRs above in the stack can migrate tonode:fs/promises. Nothing uses them yet in this PR.Like
@docusaurus/glob, it's mostly designed for internal usage and is undocumented.pathExists(path):fs.access()resolved totrue/false.outputFile(file, data, options?):mkdir(dirname, {recursive: true})thenwriteFile().readJSON(file): like fs-extra (jsonfile), ignores a leading UTF-8 BOM (JSON.parse()rejects it, and some editors like Windows Notepad add one). Read and parse errors are wrapped in a new error mentioning the file path relative to the current directory, with the original error ascause. fs-extra mutated the original error message instead.realpath(path): fs-extra'srealpathis Node's JavaScriptfs.realpath, whilefs/promisesrealpath()uses the native implementation, which normalizes path casing on macOS/Windows (checked:/USERS/foo/DESKTOP→/Users/foo/Desktop) and resolves Windows subst/network drives differently. We use it forsiteDir, and Node's module resolution keeps using the JS implementation, so switching could create path casing mismatches. This helper keeps the JS implementation.ensureDir()is not worth a helper:fs.mkdir(dir, {recursive: true}).Implementation note: the helpers call Node APIs through the default-imported module object at call time (
fs.writeFile(), not a destructured named import), so that tests can intercept them withvi.spyOn(fs, 'writeFile')onnode:fs/promises. I checked that this works in Vitest for node builtins (named imports are not intercepted).Stack
Removing
fs-extrafrom the monorepo, split into stacked PRs:@docusaurus/fspackage with fs helpersqueueFileOperation()to bound concurrently open filesnode:fs/promises, remove theirfs-extradependencyfs-extrafrom website, admin scripts and rootTest Plan
Unit tests on a real temp dir for each helper, including the BOM, the read/parse error causes, and
realpathkeeping the path casing on case-insensitive file systems (skipped elsewhere).Test links
Deploy preview: https://deploy-preview-12560--docusaurus-2.netlify.app/
No user-facing change.
(AI-assisted)
🤖 Generated with Claude Code