File System Watching and Utilities in Node.js
This group of libraries handles file system interactions in Node.js environments, though they serve different primary purposes. chokidar, fsevents, gaze, node-watch, and watchpack are designed to detect file changes (watching), which is critical for build tools, dev servers, and sync scripts. fs-extra stands apart as a utility library that extends the native fs module with extra methods like ensureDir and copy, often used alongside watchers to manipulate files. Understanding the distinction between watching for changes and performing file operations is key to selecting the right tool.
Npm Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
File System Watching and Utilities: Chokidar, FS-Extra, and Alternatives Compared
When building Node.js tools, build systems, or dev servers, you often need to detect file changes or manipulate the file system reliably. The packages chokidar, fs-extra, fsevents, gaze, node-watch, and watchpack all touch the file system, but they solve different problems. Some watch for changes, while others modify files. Let's break down how they work and when to use each one.
🎯 Core Purpose: Watching vs. Manipulating
The first distinction is whether the library watches for changes or performs actions on files.
chokidar, fsevents, gaze, node-watch, and watchpack are file watchers. They emit events when a file is created, changed, or deleted.
// chokidar: Watch for changes
const chokidar = require('chokidar');
const watcher = chokidar.watch('src/**/*.js');
watcher.on('change', path => console.log(`File ${path} changed`));
// fsevents: macOS native watching
const fsevents = require('fsevents');
const stop = fsevents.watch('src', (path, flags) => console.log(path, flags));
// gaze: Legacy glob-based watching
const { Gaze } = require('gaze');
const gaze = new Gaze('**/*.js');
gaze.on('changed', file => console.log(`${file} was changed`));
// node-watch: Pure JS watching
const watch = require('node-watch');
watch('src', { recursive: true }, (evt, name) => console.log(`${name} changed`));
// watchpack: Bundler-optimized watching
const Watchpack = require('watchpack');
const wp = new Watchpack({ aggregateTimeout: 1000 });
wp.watch({ files: [], directories: ['src'] });
wp.on('aggregated', (changes, removals) => console.log(changes));
fs-extra is a file utility. It does not watch files. It adds methods to copy, move, or ensure directories exist.
// fs-extra: File manipulation
const fs = require('fs-extra');
async function setup() {
await fs.ensureDir('dist/assets');
await fs.copy('src/assets', 'dist/assets');
}
🌍 Cross-Platform Reliability
File systems behave differently on Windows, macOS, and Linux. A good library hides these differences.
chokidar normalizes events across all OSs. It handles Windows file locking and macOS rename quirks automatically.
// chokidar: Works everywhere
const watcher = chokidar.watch('logs', { ignored: /(^|[\/\\])\../ });
// Handles Windows backslashes and macOS events uniformly
fsevents works only on macOS. Using it directly breaks your app on Windows or Linux.
// fsevents: macOS only
if (process.platform === 'darwin') {
const stop = fsevents.watch('.', log);
}
node-watch is pure JavaScript, so it runs everywhere, but it relies on polling or generic OS events which can be slower or less accurate than native bindings.
// node-watch: Cross-platform but generic
watch('.', { recursive: true }, (evt, name) => {
// Works on Windows, Linux, macOS without native deps
});
watchpack abstracts OS differences but is tuned for bundlers. It delays events to group them, which might feel laggy for interactive tools.
// watchpack: Aggregates events
wp.on('aggregated', (changes, removals) => {
// Receives batched updates rather than instant single events
});
gaze was cross-platform but struggled with performance on large trees in later years, leading to its decline.
// gaze: Legacy cross-platform
const gaze = new Gaze('**/*');
// Older implementation of cross-platform globbing
fs-extra is fully cross-platform for file operations, ensuring paths and permissions work consistently.
// fs-extra: Consistent file ops
await fs.move('./temp/file.txt', './final/file.txt');
// Handles permissions and paths across OSs
⚡ Performance at Scale
When watching thousands of files (like node_modules), performance matters.
watchpack is built for this. It aggregates changes and ignores deep trees unless specified.
// watchpack: Optimized for large trees
const wp = new Watchpack({
aggregateTimeout: 1000,
poll: false
});
wp.watch({ directories: ['node_modules'] });
chokidar is highly performant and uses fsevents on macOS automatically for speed.
// chokidar: Fast with native opts
const watcher = chokidar.watch('.', { usePolling: false });
// Uses native OS events where possible for speed
fsevents is the fastest on macOS because it is a native binding, but it lacks cross-platform support.
// fsevents: Native speed on macOS
const stop = fsevents.watch('.', log);
// Direct access to macOS FSEvents API
node-watch can use polling, which is CPU-intensive on large directories.
// node-watch: Polling option
watch('.', { recursive: true, poll: true }, callback);
// Polling consumes more CPU than native events
gaze often struggled with high file counts, leading to missed events or high memory usage in the past.
// gaze: Older performance profile
const gaze = new Gaze('**/*', { nodir: true });
// Known to have issues with very large file trees
fs-extra performance depends on the operation. copy is optimized but still synchronous in nature regarding I/O.
// fs-extra: I/O bound
await fs.copy('src', 'dist');
// Speed depends on disk I/O, not event handling
🛠️ API Simplicity and Features
Some libraries offer rich features, while others stay minimal.
fs-extra provides the most helpful utility methods, like ensureDir which creates a directory if it doesn't exist.
// fs-extra: High-level utilities
await fs.ensureDir('/tmp/complex/path');
// Creates all intermediate directories automatically
chokidar offers a clean event emitter API with options for ignoring files.
// chokidar: Event emitter API
watcher.on('add', path => console.log(`File ${path} has been added`));
watcher.on('unlink', path => console.log(`File ${path} has been removed`));
node-watch uses a simple callback or promise style.
// node-watch: Callback style
watch('src', (evt, name) => console.log(name));
watchpack uses an aggregation model, which is different from standard event emitters.
// watchpack: Aggregated events
wp.on('aggregated', (changes, removals) => {
console.log(`${changes.length} files changed`);
});
gaze used a glob-centric API which was powerful but complex.
// gaze: Glob-centric
const gaze = new Gaze(['**/*.js', '!**/node_modules/**']);
fsevents provides raw event flags that require interpretation.
// fsevents: Raw flags
fsevents.watch('.', (path, flags) => {
// Flags indicate type of change (created, removed, etc.)
});
⚠️ Deprecation and Maintenance Status
Maintenance status is critical for security and stability.
gaze is effectively deprecated. The repository is inactive, and it is not recommended for new projects.
// gaze: Do not use in new projects
// Considered legacy; use chokidar instead
fsevents is maintained but intended as a dependency for other tools, not direct usage.
// fsevents: Use via chokidar
// Direct usage limits you to macOS
chokidar, fs-extra, node-watch, and watchpack are actively maintained and safe for production.
// chokidar, fs-extra, node-watch, watchpack: Active
// Safe to install and use in 2024+
📊 Summary Table
| Package | Type | Platform | Performance | Status |
|---|---|---|---|---|
chokidar | Watcher | All | High | ✅ Active |
fs-extra | Utility | All | N/A | ✅ Active |
fsevents | Watcher | macOS Only | Very High | ✅ Active (Native) |
gaze | Watcher | All | Low | ⚠️ Legacy |
node-watch | Watcher | All | Medium | ✅ Active |
watchpack | Watcher | All | High (Batched) | ✅ Active |
💡 Final Recommendation
For 95% of use cases, choose chokidar. It is the industry standard for file watching, balancing performance, reliability, and cross-platform support. It is what powers Vite, Webpack, and many other major tools.
Use fs-extra alongside your watcher when you need to modify files. It makes tasks like copying assets or ensuring directories exist much simpler than using the native fs module.
Avoid gaze in new projects. It is outdated. Avoid direct use of fsevents unless you are writing a macOS-specific utility. Use watchpack only if you are building a bundler that needs to aggregate thousands of file events.
Final Thought: Stick to the tools that the ecosystem trusts. chokidar for watching and fs-extra for moving files will cover almost every need without introducing unnecessary risk.
How to Choose: fs-extra vs chokidar vs fsevents vs gaze vs node-watch vs watchpack
- fs-extra:
Choose
fs-extrawhen you need reliable file manipulation methods that the nativefsmodule lacks, such asensureDiror recursivecopy. It is not a watcher, so pair it withchokidarif you need to react to file changes. It is ideal for build scripts, installers, and CLI tools that modify the file system. - chokidar:
Choose
chokidarfor most production applications requiring stable, cross-platform file watching. It abstracts away OS differences and handles edge cases like file renaming or permission errors gracefully. It is the default choice for major tools like Vite and Webpack, ensuring long-term support and community trust. - fsevents:
Choose
fseventsonly if you are building a macOS-specific tool and need the absolute lowest-level access to file events. For almost all other cases, rely onchokidar, which usesfseventsinternally on macOS. Direct usage limits your application to Apple hardware and adds native compilation complexity. - gaze:
Avoid
gazefor new projects as it is considered legacy and no longer actively maintained. It was popular in the early Gulp ecosystem but has been superseded by more robust solutions likechokidar. Use it only if you are maintaining an older codebase that strictly depends on its specific globbing behavior. - node-watch:
Choose
node-watchif you need a lightweight, pure JavaScript watcher without native dependencies. It is suitable for simple scripts or environments where installing native modules is problematic. However, it may not handle high-frequency events or complex file trees as efficiently aschokidar. - watchpack:
Choose
watchpackif you are building a bundler or tool that needs to watch large directories likenode_modules. It is optimized for aggregating events and delaying notifications to avoid overwhelming the system during massive file changes. It is less suitable for general-purpose application logic compared tochokidar.
Popular Comparisons
README for fs-extra
Node.js: fs-extra
fs-extra adds file system methods that aren't included in the native fs module and adds promise support to the fs methods. It also uses graceful-fs to prevent EMFILE errors. It should be a drop in replacement for fs.
Why?
I got tired of including mkdirp, rimraf, and ncp in most of my projects.
Installation
npm install fs-extra
Usage
CommonJS
fs-extra is a drop in replacement for native fs. All methods in fs are attached to fs-extra. All fs methods return promises if the callback isn't passed.
You don't ever need to include the original fs module again:
const fs = require('fs') // this is no longer necessary
you can now do this:
const fs = require('fs-extra')
or if you prefer to make it clear that you're using fs-extra and not fs, you may want
to name your fs variable fse like so:
const fse = require('fs-extra')
you can also keep both, but it's redundant:
const fs = require('fs')
const fse = require('fs-extra')
NOTE: The deprecated constants fs.F_OK, fs.R_OK, fs.W_OK, & fs.X_OK are not exported on Node.js v24.0.0+; please use their fs.constants equivalents.
ESM
There is also an fs-extra/esm import, that supports both default and named exports. However, note that fs methods are not included in fs-extra/esm; you still need to import fs and/or fs/promises separately:
import { readFileSync } from 'fs'
import { readFile } from 'fs/promises'
import { outputFile, outputFileSync } from 'fs-extra/esm'
Default exports are supported:
import fs from 'fs'
import fse from 'fs-extra/esm'
// fse.readFileSync is not a function; must use fs.readFileSync
but you probably want to just use regular fs-extra instead of fs-extra/esm for default exports:
import fs from 'fs-extra'
// both fs and fs-extra methods are defined
Sync vs Async vs Async/Await
Most methods are async by default. All async methods will return a promise if the callback isn't passed.
Sync methods on the other hand will throw if an error occurs.
Also Async/Await will throw an error if one occurs.
Example:
const fs = require('fs-extra')
// Async with promises:
fs.copy('/tmp/myfile', '/tmp/mynewfile')
.then(() => console.log('success!'))
.catch(err => console.error(err))
// Async with callbacks:
fs.copy('/tmp/myfile', '/tmp/mynewfile', err => {
if (err) return console.error(err)
console.log('success!')
})
// Sync:
try {
fs.copySync('/tmp/myfile', '/tmp/mynewfile')
console.log('success!')
} catch (err) {
console.error(err)
}
// Async/Await:
async function copyFiles () {
try {
await fs.copy('/tmp/myfile', '/tmp/mynewfile')
console.log('success!')
} catch (err) {
console.error(err)
}
}
copyFiles()
Methods
Async
- copy
- emptyDir
- ensureFile
- ensureDir
- ensureLink
- ensureSymlink
- mkdirp
- mkdirs
- move
- outputFile
- outputJson
- pathExists
- readJson
- remove
- writeJson
Sync
- copySync
- emptyDirSync
- ensureFileSync
- ensureDirSync
- ensureLinkSync
- ensureSymlinkSync
- mkdirpSync
- mkdirsSync
- moveSync
- outputFileSync
- outputJsonSync
- pathExistsSync
- readJsonSync
- removeSync
- writeJsonSync
NOTE: You can still use the native Node.js methods. They are promisified and copied over to fs-extra. See notes on fs.read(), fs.write(), & fs.writev()
What happened to walk() and walkSync()?
They were removed from fs-extra in v2.0.0. If you need the functionality, walk and walkSync are available as separate packages, klaw and klaw-sync.
Third Party
CLI
fse-cli allows you to run fs-extra from a console or from npm scripts.
TypeScript
If you like TypeScript, you can use fs-extra with it: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/fs-extra
File / Directory Watching
If you want to watch for changes to files or directories, then you should use chokidar.
Obtain Filesystem (Devices, Partitions) Information
fs-filesystem allows you to read the state of the filesystem of the host on which it is run. It returns information about both the devices and the partitions (volumes) of the system.
Misc.
- fs-extra-debug - Send your fs-extra calls to debug.
- mfs - Monitor your fs-extra calls.
Hacking on fs-extra
Wanna hack on fs-extra? Great! Your help is needed! fs-extra is one of the most depended upon Node.js packages. This project
uses JavaScript Standard Style - if the name or style choices bother you,
you're gonna have to get over it :) If standard is good enough for npm, it's good enough for fs-extra.
What's needed?
- First, take a look at existing issues. Those are probably going to be where the priority lies.
- More tests for edge cases. Specifically on different platforms. There can never be enough tests.
- Improve test coverage.
Note: If you make any big changes, you should definitely file an issue for discussion first.
Running the Test Suite
fs-extra contains hundreds of tests.
npm run lint: runs the linter (standard)npm run unit: runs the unit testsnpm run unit-esm: runs tests forfs-extra/esmexportsnpm test: runs the linter and all tests
When running unit tests, set the environment variable CROSS_DEVICE_PATH to the absolute path of an empty directory on another device (like a thumb drive) to enable cross-device move tests.
Windows
If you run the tests on the Windows and receive a lot of symbolic link EPERM permission errors, it's
because on Windows you need elevated privilege to create symbolic links. You can add this to your Windows's
account by following the instructions here: http://superuser.com/questions/104845/permission-to-make-symbolic-links-in-windows-7
However, I didn't have much luck doing this.
Since I develop on Mac OS X, I use VMWare Fusion for Windows testing. I create a shared folder that I map to a drive on Windows.
I open the Node.js command prompt and run as Administrator. I then map the network drive running the following command:
net use z: "\\vmware-host\Shared Folders"
I can then navigate to my fs-extra directory and run the tests.
Naming
I put a lot of thought into the naming of these functions. Inspired by @coolaj86's request. So he deserves much of the credit for raising the issue. See discussion(s) here:
- https://github.com/jprichardson/node-fs-extra/issues/2
- https://github.com/flatiron/utile/issues/11
- https://github.com/ryanmcgrath/wrench-js/issues/29
- https://github.com/substack/node-mkdirp/issues/17
First, I believe that in as many cases as possible, the Node.js naming schemes should be chosen. However, there are problems with the Node.js own naming schemes.
For example, fs.readFile() and fs.readdir(): the F is capitalized in File and the d is not capitalized in dir. Perhaps a bit pedantic, but they should still be consistent. Also, Node.js has chosen a lot of POSIX naming schemes, which I believe is great. See: fs.mkdir(), fs.rmdir(), fs.chown(), etc.
We have a dilemma though. How do you consistently name methods that perform the following POSIX commands: cp, cp -r, mkdir -p, and rm -rf?
My perspective: when in doubt, err on the side of simplicity. A directory is just a hierarchical grouping of directories and files. Consider that for a moment. So when you want to copy it or remove it, in most cases you'll want to copy or remove all of its contents. When you want to create a directory, if the directory that it's suppose to be contained in does not exist, then in most cases you'll want to create that too.
So, if you want to remove a file or a directory regardless of whether it has contents, just call fs.remove(path). If you want to copy a file or a directory whether it has contents, just call fs.copy(source, destination). If you want to create a directory regardless of whether its parent directories exist, just call fs.mkdirs(path) or fs.mkdirp(path).
Credit
fs-extra wouldn't be possible without using the modules from the following authors:
License
Licensed under MIT
Copyright (c) 2011-2024 JP Richardson