jprichardson /node-fs-extra

Node.js: extra methods for the fs object like copy(), remove(), mkdirs()

★ 9,596⑂ 791👁 89⑃ 417● 672▤ 0
JavaScriptMITCreated 2011-11-16
+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

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON