• Stars
    star
    9,368
  • Rank 3,673 (Top 0.08 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created over 12 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

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

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.

npm Package License build status downloads per month JavaScript Style Guide

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:

const fs = require('fs') // this is no longer necessary

you can now do this:

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:

const fse = require('fs-extra')

you can also keep both, but it's redundant:

const fs = require('fs')
const fse = require('fs-extra')

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 seperately:

import { readFileSync } from 'fs'
import { readFile } from 'fs/promises'
import { outputFile, outputFileSync } from 'fs-extra/esm'

Default exports are supported:

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:

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:

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

Sync

NOTE: You can still use the native Node.js methods. They are promisified and copied over to fs-extra. See notes on fs.read(), fs.write(), & fs.writev()

What happened to walk() and walkSync()?

They were removed from fs-extra in v2.0.0. If you need the functionality, walk and walkSync are available as separate packages, klaw and klaw-sync.

Third Party

CLI

fse-cli allows you to run fs-extra from a console or from npm scripts.

TypeScript

If you like TypeScript, you can use fs-extra with it: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/fs-extra

File / Directory Watching

If you want to watch for changes to files or directories, then you should use chokidar.

Obtain Filesystem (Devices, Partitions) Information

fs-filesystem allows you to read the state of the filesystem of the host on which it is run. It returns information about both the devices and the partitions (volumes) of the system.

Misc.

Hacking on fs-extra

Wanna hack on fs-extra? Great! Your help is needed! fs-extra is one of the most depended upon Node.js packages. This project uses JavaScript Standard Style - if the name or style choices bother you, you're gonna have to get over it :) If standard is good enough for npm, it's good enough for fs-extra.

js-standard-style

What's needed?

  • First, take a look at existing issues. Those are probably going to be where the priority lies.
  • More tests for edge cases. Specifically on different platforms. There can never be enough tests.
  • Improve test coverage.

Note: If you make any big changes, you should definitely file an issue for discussion first.

Running the Test Suite

fs-extra contains hundreds of tests.

  • npm run lint: runs the linter (standard)
  • npm run unit: runs the unit tests
  • npm run unit-esm: runs tests for fs-extra/esm exports
  • npm test: runs the linter and all tests

When running unit tests, set the environment variable CROSS_DEVICE_PATH to the absolute path of an empty directory on another device (like a thumb drive) to enable cross-device move tests.

Windows

If you run the tests on the Windows and receive a lot of symbolic link EPERM permission errors, it's because on Windows you need elevated privilege to create symbolic links. You can add this to your Windows's account by following the instructions here: http://superuser.com/questions/104845/permission-to-make-symbolic-links-in-windows-7 However, I didn't have much luck doing this.

Since I develop on Mac OS X, I use VMWare Fusion for Windows testing. I create a shared folder that I map to a drive on Windows. I open the Node.js command prompt and run as Administrator. I then map the network drive running the following command:

net use z: "\\vmware-host\Shared Folders"

I can then navigate to my fs-extra directory and run the tests.

Naming

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.

For example, fs.readFile() and 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: fs.mkdir(), fs.rmdir(), fs.chown(), etc.

We have a dilemma though. How do you consistently name methods that perform the following POSIX commands: cp, cp -r, mkdir -p, and rm -rf?

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). 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.mkdirs(path) or fs.mkdirp(path).

Credit

fs-extra wouldn't be possible without using the modules from the following authors:

License

Licensed under MIT

Copyright (c) 2011-2017 JP Richardson

More Repositories

1

string.js

Extra JavaScript string methods.
JavaScript
1,801
star
2

node-jsonfile

Easily read/write JSON files.
JavaScript
1,200
star
3

node-google

A Node.js module to search and scrape Google.
JavaScript
453
star
4

sublime-js-snippets

Snippets for JavaScript / JS Programming in Sublime Text 2 & 3
407
star
5

electron-mocha

Run Mocha tests in Electron
JavaScript
345
star
6

node-klaw

A Node.js file system walker with a Readable stream interface. Extracted from fs-extra.
JavaScript
314
star
7

electron-window

Convenience methods for Electron windows.
JavaScript
289
star
8

node-suppose

Like UNIX Expect, but for Node.js.
JavaScript
252
star
9

node-death

Gracefully cleanup when termination signals are sent to your process.
JavaScript
180
star
10

electron-ipc-stream

Duplex stream that runs over Electron's IPC
JavaScript
151
star
11

asciiflow

ASCII diagrams and drawing on the web (GWT)
Java
135
star
12

tin

Easily manage package.json, component.json, and bower.json files.
JavaScript
92
star
13

is-electron-renderer

Check if code is running in Electron renderer process
JavaScript
76
star
14

node-github-download

Easily download Github repos without dependencies such as Git, Tar, Unzip, etc.
JavaScript
75
star
15

secure-random

A simple JavaScript component to normalize the creation of cryptographically strong random values.
JavaScript
61
star
16

iceden

Maybe something like Firebase?
JavaScript
60
star
17

GeneratePushCerts

Automation of Generating Push Certificates for iOS Devices
Ruby
57
star
18

node-batchflow

Batch process collections in parallel or sequentially.
JavaScript
51
star
19

node-kexec

Node.js exec function to replace running process; like Ruby's exec.
C++
50
star
20

tape-promise

Promise and async/await support for Tape
JavaScript
45
star
21

talks-ncc3-demo

Demo from Nebraska Code Camp #3
JavaScript
40
star
22

node-nextflow

A simple control-flow library for Node.js targetted towards CoffeeScript developers.
CoffeeScript
38
star
23

node-scrap

A simple screen scraper module that uses jQuery style semantics.
JavaScript
33
star
24

react-qr

A React.js QR Code component.
JavaScript
31
star
25

node-canada

Cities and provinces from Canada for JavaScript
JavaScript
28
star
26

ansible-redis

Ansible playbook to install redis.
Shell
27
star
27

cross-zip-cli

Zip/Unzip directories cross platform from the CLI. Great for npm scripts.
JavaScript
25
star
28

node-path-extra

Node.js: extra methods for the path object.
JavaScript
23
star
29

readline-go

golang: Easily read lines from a stream such as `stdin` for a file. Supports either `\n`, `\r\n`, or mixed.
Go
22
star
30

CommonLib

A .NET Library With Utility Classes and Methods
C#
19
star
31

least-squares

JavaScript component for linear least squares regression analysis.
JavaScript
18
star
32

node-linkscrape

A Node.js module to scrape and normalize links from an HTML string.
JavaScript
15
star
33

FridayThe13th

Fast JSON Parser for Silverlight or .NET
C#
14
star
34

jsock

JavaScript component for easy JSON handling over sockets or streams. Works in Node.js or the browser.
JavaScript
13
star
35

ip-location

Get an IP or hostname location geo coordinates.
JavaScript
13
star
36

rr

A simple JavaScript component to iterate an array round robin.
JavaScript
12
star
37

node-packpath

Easily find the path(s) of package.json.
JavaScript
12
star
38

node-markdown-extra

Extra markdown methods.
JavaScript
12
star
39

buffer-json

JSON reviver/replacer methods for JavaScript Buffer type.
JavaScript
12
star
40

npm-latest

Quickly find the latest version of a package in npm.
JavaScript
12
star
41

keychain_manager

Ruby Gem for OS X Keychain Access
Ruby
11
star
42

npm-research

Nice little utility to help you research NPM packages.
JavaScript
10
star
43

fix-dropbox-node_modules-symlinks

Fix Dropbox `node_modules/.bin/` symlinks.
JavaScript
10
star
44

logmeup

LogMeUp Server - View any log files real-time in your web browser.
JavaScript
10
star
45

mars

Forget live coding, easy code demos.
JavaScript
9
star
46

bitcoin-faucet

A Node.js app to easily create a programmable Bitcoin Testnet faucet. This allows you to easily test your Bitcoin applications.
JavaScript
9
star
47

angular-bluebird

An AngularJS service for Bluebird promise library.
JavaScript
8
star
48

node-cfs

Node.js conditional file streams
JavaScript
7
star
49

d3-measure-text

A JavaScript component to measure the the width and height of SVG text.
JavaScript
7
star
50

atom-rename-tabs

Rename tabs titles with previous directory. Consistent with Sublime Text Editor behavior.
JavaScript
7
star
51

d3-dragrect

A JavaScript D3 drag selection rectangle component.
JavaScript
6
star
52

secret-box

Encrypt and decrypt secrets. Built on AES-256-GCM and Scrypt for now.
JavaScript
6
star
53

MemMapCache

A .NET caching solution that uses memory mapping.
C#
5
star
54

ospath

A JavaScript component that provides operating specific path values.
JavaScript
5
star
55

potter-wordpress

Command line tool to export WordPress to static Markdown.
JavaScript
5
star
56

jsontocsv

Convert lines of JSON data to CSV
JavaScript
5
star
57

d3-tooltip

This is a JavaScript d3 tooltip component.
JavaScript
5
star
58

mongo_install

Ruby script to install download, install, and setup MongoDB as a service on a Ubuntu or Debian box.
Ruby
5
star
59

node-batchtransform

Batch transform/convert a collection of files e.g. convert a collection of markdown template files to html files.
JavaScript
5
star
60

is-async-fn

Check if something is an ES7 async function.
JavaScript
4
star
61

node-dh

Distributed hash. Simple Node.js wrapper for Redis hash.
JavaScript
4
star
62

spend

A JavaScript component to create simple Bitcoin / Testnet transactions for integration testing with the actual network.
JavaScript
4
star
63

ripdb

100% JavaScript embeddable JSON time series database.
JavaScript
4
star
64

procbits.com

Home of my current coding blog.
HTML
3
star
65

react-password

A React.js component for password inputs.
JavaScript
3
star
66

cb-insight

Common Blockchain wrapper for Bitpay Insight API
JavaScript
3
star
67

ansible-rethinkdb

Ansible playbook to setup a RethinkDB.
3
star
68

node-readline-prompter

Easily prompt the user with a series of questions.
JavaScript
3
star
69

node-worddump

Dump or Export your WordPress blog content.
JavaScript
3
star
70

atom-javascript-standard-snippets

JavaScript Standard Style Snippets for Atom
CoffeeScript
3
star
71

pottercms

https://github.com/skywrite/sky
JavaScript
3
star
72

issue-links

Help to keep tidy `CHANGELOG.md`/`HISTORY.md` files by keeping your GitHub Issue links up to date.
JavaScript
3
star
73

d3-chart

A simple JavaScript D3.js chart.
3
star
74

node-wp2md

Convert your WordPress blog to Markdown.
JavaScript
3
star
75

create-output-stream

Node.js: exactly like `fs.createWriteStream`, but if the directory does not exist, it's created.
JavaScript
3
star
76

node-parentpath

Find a path in a parent directory.
JavaScript
3
star
77

buzz

Keep an app running indefinitely, kill it occasionally if you want.
JavaScript
3
star
78

node-tweezers

Extract mustache tokens from a file or string.
JavaScript
2
star
79

node-logmeup

Node.js plugin to interface to LogMeUp
CoffeeScript
2
star
80

cooking-recipes

I'm starting to write down recipes that I've tried.
2
star
81

node-testutil

Node.js testing utilities
JavaScript
2
star
82

node-autoresolve

A simple Node.js module to auto resolve package paths.
JavaScript
2
star
83

ip-location-cli

Command line utility to fetch IP geo location or your own location.
JavaScript
2
star
84

electron-menu

Convenience module to build Electron menu templates.
JavaScript
2
star
85

node-markdown-page

Methods for parsing a markdown page for a blog post or documentation.
JavaScript
2
star
86

node-vcsurl

Convert VCS repository URLs like Github or Bitbucket to their http equivalents.
JavaScript
2
star
87

node-dq

Simple Node.js priority queue built on Redis.
JavaScript
2
star
88

ymd

JavaScript component to return the year, month, and day string.
JavaScript
2
star
89

terst

A JavaScript testing component with a terse syntax. Supported in both Node.js and the browser.
JavaScript
2
star
90

browser-storage

Normalizes local-storage behavior between node and browser
JavaScript
2
star
91

is-os-cli

CLI utility to check if operating system. Useful for npm scripts.
JavaScript
2
star
92

node-batchfile

JavaScript
2
star
93

prevent-backspace

Prevents the backspace from navigating back in the browser.
JavaScript
2
star
94

github-issues-stream

A Node.js readable stream for Github issues.
JavaScript
1
star
95

goatee-go

Non-verbose testing in Go
Go
1
star
96

node-markdown-walker

Simple directory walker that specifically looks for markdown files.
JavaScript
1
star
97

node-cl

Easily create command line programs and interfaces in Node.js.
JavaScript
1
star
98

node-proxyinfo

Get information about HTTP proxy servers
CoffeeScript
1
star
99

trinity

JavaScript
1
star
100

node-qflow

A very simple data queue processing library.
JavaScript
1
star