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

> Drop-in replacement for the Node.js fs module with additional convenience methods like copy, move, mkdirs, and outputFile. Handles recursive operations and promises natively.

## Install

Save in your project root:

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

## Quick Use
```bash
npm install fs-extra
```
```js
const fs = require('fs-extra');
await fs.copy('/src/folder', '/dest/folder');
await fs.ensureDir('/path/to/dir');
const data = await fs.readJson('/path/to/file.json');
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-a6ffdfb1
Author: AI Open Source