fs-extra — Enhanced File System Methods for Node.js

Introduction

fs-extra adds file system methods that are not included in the native Node.js fs module. It is a drop-in replacement: every method from fs is re-exported, so you can swap require('fs') with require('fs-extra') without changing existing code. The library provides recursive copy, move, remove, and directory creation out of the box, all with promise support.

What fs-extra Does

• Adds copy() for recursive file and directory copying with filter support
• Provides ensureDir() and ensureFile() to create paths that may not exist
• Includes move() for cross-device file and directory moves with overwrite options
• Offers readJson() and writeJson() with built-in parsing and pretty-printing
• Re-exports all native fs methods, both callback and promise-based

Architecture Overview

fs-extra is a thin wrapper around Node.js built-in fs and fs/promises modules. It adds higher-level operations implemented in pure JavaScript with no native bindings. Recursive operations use a walk-and-apply pattern that respects symlinks and file permissions. The library detects whether a callback is provided and returns a promise when it is not, supporting both async/await and callback styles transparently.

Self-Hosting & Configuration

• Install via npm: npm install fs-extra
• Replace require('fs') with require('fs-extra') for a seamless upgrade
• No configuration files needed; options are passed per method call
• Works with Node.js 14+ and supports both CommonJS and ESM imports
• Zero external dependencies beyond Node.js built-ins

Key Features

• Recursive copy with glob-based filtering: fs.copy(src, dest, { filter })
• Atomic write operations via outputFile() and outputJson() that create parent directories automatically
• Cross-device move operations that fall back to copy-then-remove when rename fails
• JSON read/write with options for encoding, replacer, spaces, and error handling
• Empty directory creation and removal with ensureDir() and emptyDir()

Comparison with Similar Tools

• Node.js fs — Built-in but lacks recursive copy, move, and ensureDir; fs-extra fills these gaps
• shelljs — Shell command wrappers; fs-extra is lower-level and more portable
• graceful-fs — Patches fs to handle EMFILE errors; fs-extra re-exports graceful-fs internally
• cpy — Focused on copying with glob patterns; fs-extra is a broader fs replacement
• rimraf — Recursive remove only; fs-extra includes remove() plus many other operations

FAQ

Q: Is fs-extra a full drop-in replacement for fs? A: Yes. It re-exports every method from the native fs module, so existing code works unchanged after switching the import.

Q: Does fs-extra support TypeScript? A: Yes. Type definitions are included via @types/fs-extra or bundled in newer versions. All methods have full type signatures.

Q: How does fs-extra handle errors on recursive operations? A: Errors propagate immediately by default. For copy operations, you can pass an errorOnExist option or a filter function to skip problematic files.

Q: Is fs-extra suitable for production use? A: Yes. It is one of the most downloaded npm packages with billions of downloads and is used by major tools like Create React App, Angular CLI, and Electron Forge.

Sources

• https://github.com/jprichardson/node-fs-extra
• https://www.npmjs.com/package/fs-extra