jprichardson /node-fs-extra
Node.js: extra methods for the fs object like copy(), remove(), mkdirs()
★ 9,596⑂ 791👁 89⑃ 417● 672▤ 0
+0
Daily
9,596
stars
791
forks
89
watchers
417
prs
672
issues
0
releases
README
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:
js
const fs = require('fs') // this is no longer necessary
you can now do this:
js
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:
js
const fse = require('fs-extra')
you can also keep both, but it's redundant:
js
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:
js
import { readFileSync } from 'fs'
import { readFile } from 'fs/promises'
import { outputFile, outputFileSync } from 'fs-extra/esm'
Default exports are supported:
js
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:
js
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:
js
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
-Top issues
#1037Feature request: isEmptyDir()12 comments · 2024-03-19#686feature request: fs.softDelete or the like?12 comments · 2019-05-14#912fs.cp coming to Node.js core7 comments · 2021-07-15#1054Update devDependencies5 comments · 2025-08-12#575Problems when dealing with invalidly-encoded filenames5 comments · 2018-05-02#668--merge option for move4 comments · 2019-04-05#542Inconsistency between readJson and readJsonSync when file does not exist4 comments · 2018-01-22#1086areIdentical() returns true for different files when filesystem reports 0n inode values3 comments · 2026-09-25