fs-extra contains methods that aren't included in the vanilla Node.js fs package. Such as mkdir -p, cp -r, and rm -rf.
This module adds a few extra file system methods that aren't included in the native
fs module. It is a drop in replacement for
I got tired of including
cp -r in most of my projects.
npm install --save fs-extra
fs-extra is a drop in replacement for native
fs. All methods in
fs are unmodified and attached to
You don't ever need to include the original
fs module again:
var fs = require'fs' //this is no longer necessary
you can now do this:
var fs = require'fs-extra'; //var fs = require('fs')
or if you prefer to make it clear that you're using
fs-extra and not
fs, you may want
to do this:
//var fs = require('fs')var fse = require'fs-extra'
you can also keep, both, but it's redundant:
var fs = require'fs'fse = require'fs-extra'
NOTE: You can still use the native Node.js methods. They are copied over to
Copy a file or directory. The directory can have contents. Like
var fs = require'fs-extra';fscopy'/tmp/myfile' '/tmp/mynewfile'if err return console.errorerr;console.log"success!"; //copies filefscopy'/tmp/mydir' '/tmp/mynewdir'if err return console.errorerr;console.log"success!"; //copies directory, even if it has subdirectories or files
Creates a file. If the file that is requested to be created is in directories that do not exist, these directories are created. If the file already exists, it is NOT MODIFIED.
var fs = require'fs-extra'var file = '/tmp/this/path/does/not/exist/file.txt'fscreateFilefileconsole.logerr; //null//file has now been created, including the directory it is to be placed in
Creates a directory. If the parent hierarchy doesn't exist, it's created. Like
var fs = require'fs-extra';fsmkdirs'/tmp/some/long/path/that/prob/doesnt/exist'if err return console.errorerr;console.log"success!";fsmkdirsSync'/tmp/another/path';
Almost the same as
writeFile, except that if the directory does not exist, it's created.
var fs = require'fs-extra'var file = '/tmp/this/path/does/not/exist/file.txt'fsoutputFilefile 'hello!'console.logerr; //nullfsreadFilefile 'utf8'console.logdata; //hello!
Almost the same as
writeJson, except that if the directory does not exist, it's created.
var fs = require'fs-extra'var file = '/tmp/this/path/does/not/exist/file.txt'fsoutputJsonfile name: 'JP'console.logerr; //nullfsreadJsonfileconsole.logdataname; //'JP
Reads a JSON file and then parses it into an object.
options are the same that you'd pass to
var fs = require'fs-extra';fsreadJson'./package.json'console.logpackageObjversion; //0.1.3;
Removes a file or directory. The directory can have contents. Like
var fs = require'fs-extra';fsremove'/tmp/myfile'if err return console.errorerr;console.log"success!";fsremoveSync'/home/jprichardson'; //I just deleted my entire HOME directory.
Writes an object to a JSON file.
options are the same that you'd pass to
var fs = require'fs-extra';fswriteJson'./package.json' name: 'fs-extra'console.logerr;;
This contains items that I'm considering doing. I'd love community feedback.
- File system walker. I really like this one: https://github.com/daaku/nodejs-walker ... this might be adding too much. Thoughts?
- File/directory tree watcher. There are quite a few. ... this also might be adding too much. I like this one: https://github.com/paulmillr/chokidar but I don't like that it's written in CoffeeScript. Thoughts?
- Method to move files.
- Thinking about moving
mkdirpscode into this library. I'd like fs-extra to be a stable library that module authors can depend upon. A bunch of other dependencies kinda sucks for modules/libraries. (I'm leaning against this now.)
- Change documentation to use the
fseprefix instead of
fs. This may encourage people to start using
fseas a prefix and hence make their code clearer that they're not using the native
fs. I'm very undecided on this one since
fs-extrais a drop in replacement for the native
fs. (I'm leaning against this now.)
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:
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.
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:
We have a dilemma though. How do you consistently name methods that perform the following POSIX commands:
mkdir -p, and
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) or its alias
fs.delete(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-extra wouldn't be possible without using the modules from the following authors:
If you want to contribute, please add a test. Also, don't change the version in
- [*] JP Richardson
- [*] Mike McNeil
- [*] Ian Crowther
- [*] Stephen Mathieson
- [*] Srirangan
- [*] Uli Köhler
-  Jim Higson
<your name here>
Licensed under MIT
Copyright (c) 2011-2013 JP Richardson