fs-extra vs graceful-fs vs mkdirp vs node-fs vs rimraf
Node.js ファイルシステム操作ユーティリティの比較と選定ガイド
fs-extragraceful-fsmkdirpnode-fsrimraf類似パッケージ:

Node.js ファイルシステム操作ユーティリティの比較と選定ガイド

fs-extra, graceful-fs, mkdirp, node-fs, rimraf は、Node.js 標準の fs モジュールを補完または拡張するパッケージです。これらはディレクトリの再帰的作成、ファイルの削除、エラーハンドリングの強化などを提供しますが、Node.js のバージョンアップにより標準機能で賄える部分も増えています。本比較では、各パッケージの役割と、現代の Node.js 環境における適切な使い分けを解説します。

npmのダウンロードトレンド

3 年

GitHub Starsランキング

統計詳細

パッケージ
ダウンロード数
Stars
サイズ
Issues
公開日時
ライセンス
fs-extra09,59559.3 kB131ヶ月前MIT
graceful-fs01,30232.5 kB493年前ISC
mkdirp0199107 kB13年前MIT
node-fs068-113年前-
rimraf05,851262 kB106ヶ月前BlueOak-1.0.0

Node.js ファイルシステムユーティリティ:fs-extra, graceful-fs, mkdirp, rimraf, node-fs

Node.js でファイル操作を行う際、標準の fs モジュールだけでは不便な場面があります。fs-extra, graceful-fs, mkdirp, rimraf, node-fs は、それぞれの課題を解決するために登場しましたが、Node.js の進化により役割が変化しています。

📂 ディレクトリ作成:再帰的サポートの違い

mkdirp は、存在しない親ディレクトリも含めて再帰的に作成します。

  • 古い Node.js バージョンでは必須でしたが、現在は標準機能で代用可能です。
// mkdirp
const mkdirp = require('mkdirp');
await mkdirp('/tmp/foo/bar/baz');

fs-extra は ensureDir を提供します。

  • ディレクトリが既に存在してもエラーにならず、安全に作成できます。
// fs-extra
const fs = require('fs-extra');
await fs.ensureDir('/tmp/foo/bar/baz');

node-fs は標準 fs のラッパーですが、現在では不要です。

  • 標準 fs を使うべきであり、このパッケージを使う理由はありません。
// node-fs (非推奨)
const fs = require('node-fs');
fs.mkdir('/tmp/foo/bar/baz', { recursive: true }); // 標準 fs と同様

標準 fs (Node.js 10.12+)

  • 現在では recursive: true オプションで同等のことが可能です。
// Native fs
const fs = require('fs');
await fs.promises.mkdir('/tmp/foo/bar/baz', { recursive: true });

🗑️ 削除操作:rimraf vs 標準 fs.rm

rimraf は rm -rf の Node.js 実装です。

  • 過去には Windows のパス問題などを解決していましたが、現在は標準機能で十分です。
// rimraf
const rimraf = require('rimraf');
rimraf.sync('/tmp/foo/bar');

fs-extra は remove メソッドを提供します。

  • rimraf と同様にファイルでもディレクトリでも動作します。
// fs-extra
const fs = require('fs-extra');
await fs.remove('/tmp/foo/bar');

標準 fs (Node.js 14.14+)

  • fs.rm が追加され、rimraf の主な役割を終えました。
// Native fs
const fs = require('fs');
await fs.promises.rm('/tmp/foo/bar', { recursive: true, force: true });

🛠️ 追加機能:fs-extra の独自メソッド

fs-extra はコピーや移動、JSON 操作を簡単に行えます。

  • 標準 fs では複数行かかる操作が単一メソッドで完結します。
// fs-extra
const fs = require('fs-extra');
await fs.copy('/src/file.txt', '/dest/file.txt');
await fs.move('/src/file.txt', '/dest/file.txt');
const data = await fs.readJson('/data/config.json');

graceful-fs

  • 追加機能はありません。エラーハンドリングを強化するだけです。
// graceful-fs
const fs = require('graceful-fs');
// fs 全体を置き換えて使用
fs.readFile('/tmp/file.txt', ...);

node-fs

  • 独自機能はなく、標準 fs とほぼ同じです。
// node-fs
const fs = require('node-fs');
fs.readFile('/tmp/file.txt', ...);

⚠️ エラーハンドリングと信頼性

graceful-fs は EMFILE エラー(ファイル記述子の枯渇)を処理します。

  • 大量のファイルを操作する CLI ツールでは重宝されます。
// graceful-fs
const fs = require('graceful-fs');
// require するだけで自動的に fs モジュールをパッチします

fs-extra

  • graceful-fs をオプションでラッパーとして使用できます。
// fs-extra with graceful-fs
const fs = require('fs-extra');
// 内部で graceful-fs を使用可能

rimraf / mkdirp / node-fs

  • 特別なエラーハンドリング機能はありません。
// rimraf
const rimraf = require('rimraf');
// エラーはそのままスローされます

🚫 非推奨パッケージに注意

node-fs

  • 新しいプロジェクトでは使用しないでください。
  • Node.js 標準の fs モジュールが存在するため、このラッパーは不要です。
  • 保守されていない可能性が高く、依存関係を増やす意味がありません。

rimraf / mkdirp

  • Node.js 14 以上を使用している場合、標準 fs で十分です。
  • 古いバージョン(Node 12 以下)をサポートする必要がある場合のみ検討してください。
// Avoid node-fs
const fs = require('node-fs'); // ❌ Bad

// Use Native fs
const fs = require('fs'); // ✅ Good

📊 結論:どれを選ぶべきか

現代の Node.js 開発では、標準 fs モジュールで十分なケースが増えています。

  • fs-extra: 開発効率を上げたい場合(copy, move, ensureDir などが便利)。
  • graceful-fs: 大量ファイル操作で EMFILE エラーが出る場合。
  • mkdirp / rimraf: 古い Node.js バージョンをサポートする場合のみ。
  • node-fs: 絶対に使用しない。標準 fs を使いましょう。

依存関係を減らし、標準機能で済むところは標準機能を使うのが、長期的なメンテナンス性に繋がります。

選び方: fs-extra vs graceful-fs vs mkdirp vs node-fs vs rimraf

  • fs-extra:

    copy, move, ensureDir などの便利なメソッドが必要な場合に選択します。標準 fs では複数ステップかかる操作を単一メソッドで実行できるため、開発効率が向上します。大規模なファイル操作を行うプロジェクトや、コードの可読性を高めたい場合に最適です。

  • graceful-fs:

    大量のファイルを同時に処理する際に発生する EMFILE エラー(ファイル記述子の枯渇)を回避したい場合に選択します。主に CLI ツールやパッケージマネージャなど、システムリソースの限界に近い操作を行うツールで有用です。通常の Web アプリケーションでは不要なことが多いです。

  • mkdirp:

    Node.js 10.12 未満の古い環境をサポートする必要がある場合にのみ選択します。それ以上のバージョンでは、標準 fs.mkdir の recursive: true オプションで同等の機能を提供するため、依存関係を増やす意味はありません。

  • node-fs:

    新しいプロジェクトでは絶対に使用しないでください。これは標準 fs モジュールのラッパーに過ぎず、追加の価値はありません。標準の fs モジュールを使用することで、不要な依存関係を排除し、セキュリティリスクを低減できます。

  • rimraf:

    Node.js 14.14 未満の環境で、再帰的にファイルやディレクトリを削除する必要がある場合に選択します。それ以上のバージョンでは、標準 fs.rm の recursive: true オプションで代用可能です。既存のレガシーコードを維持する場合を除き、新規採用は推奨されません。

fs-extra の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.

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')

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:

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-2024 JP Richardson