fs vs fs-extra vs fs-extra-promise
Node.js におけるファイルシステム操作ライブラリの比較
fsfs-extrafs-extra-promise類似パッケージ:

Node.js におけるファイルシステム操作ライブラリの比較

fs、fs-extra、fs-extra-promise はいずれも Node.js におけるファイルシステム操作を目的としたパッケージですが、その機能範囲と非同期処理への対応に大きな違いがあります。fs は Node.js 標準のモジュールで基本的なファイル操作を提供します。fs-extra は fs を拡張し、再帰的なコピー・削除などの高レベルなユーティリティと、Promise ベースの API をネイティブにサポートします。一方、fs-extra-promise はかつて fs-extra の Promise 対応を補助するラッパーとして存在しましたが、現在は非推奨となっており、新規プロジェクトでの使用は推奨されません。

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

3 年

GitHub Starsランキング

統計詳細

パッケージ
ダウンロード数
Stars
サイズ
Issues
公開日時
ライセンス
fs0163-510年前ISC
fs-extra09,58859.3 kB122ヶ月前MIT
fs-extra-promise044-79年前MIT

Node.js ファイルシステム操作:fs vs fs-extra vs fs-extra-promise

Node.js でファイルやディレクトリを扱う際、標準の fs モジュールから始まり、より高機能な代替手段として fs-extra やその派生パッケージが登場してきました。しかし、これら3つの選択肢には明確な違いと適切な使用場面があります。特に、現代の非同期処理への対応や API の使いやすさという点で大きな差が出ます。以下では、実際の開発現場での判断材料になるよう、技術的観点から深く比較します。

📁 基本的なファイル操作:コールバック vs Promise

fs(Node.js 組み込み) は、コールバックベースの API と、Promise を返す .promises サブモジュールの両方を提供しています。

// fs: コールバックスタイル
const fs = require('fs');
fs.readFile('file.txt', 'utf8', (err, data) => {
  if (err) throw err;
  console.log(data);
});

// fs: Promise スタイル(.promises)
const { promises: fsPromises } = require('fs');
async function read() {
  const data = await fsPromises.readFile('file.txt', 'utf8');
  console.log(data);
}

fs-extra は、fs のすべての機能を拡張し、Promise をネイティブにサポートします。.promises サブモジュールを使わずに直接 async/await が可能です。

// fs-extra: 直接 Promise 対応
const fse = require('fs-extra');
async function read() {
  const data = await fse.readFile('file.txt', 'utf8');
  console.log(data);
}

fs-extra-promise は、かつて fs-extra の Promise 対応を補完するラッパーとして存在していましたが、公式に非推奨(deprecated) とされています。npm ページおよび GitHub リポジトリに明記されており、新規プロジェクトでの使用は避けるべきです。

💡 注:fs-extra がバージョン 1.0.0(2016年)以降で Promise をネイティブサポートしたため、fs-extra-promise は不要になりました。

🔧 高度なユーティリティ:再帰的コピー・削除など

fs は基本的な I/O 操作に特化しており、ディレクトリの再帰的削除やディレクトリ全体のコピーといった高レベル操作は提供していません。

// fs: 再帰的削除はできない(Node.js 14.14.0 以降で fs.rmdirSync(path, { recursive: true }) が追加されたが、非推奨)
// 現在は fs.rmSync(path, { recursive: true }) が推奨だが、依然として低レベル

一方、fs-extra はこうしたユースケースをカバーする便利メソッドを多数提供しています。

// fs-extra: 再帰的コピー・削除
const fse = require('fs-extra');

// ディレクトリ全体をコピー
await fse.copy('./src', './dest');

// ディレクトリを再帰的に削除
await fse.remove('./old-dir');

// ファイルやディレクトリが存在するか確認
if (await fse.pathExists('./config.json')) {
  // ...
}

fs-extra-promise はこれらの機能をラップして Promise 化していましたが、前述の通り非推奨であり、コード例を示す意味はありません。

🔄 非同期処理の統一性とメンテナンス性

fs を使う場合、コールバックと Promise の混在を避けるために、常に fs.promises を使う必要があります。これはコードの一貫性を保つ上で重要ですが、若干冗長です。

// fs: 必ず .promises を経由
const { promises } = require('fs');
await promises.writeFile('log.txt', 'data');

fs-extra は、すべてのメソッドが Promise を返すため、開発者が意識せずに async/await を使えます。また、同期メソッド(readFileSync など)もそのまま利用可能で、必要に応じて使い分けられます。

// fs-extra: 同期・非同期の両方を自然にサポート
const fse = require('fs-extra');

// 非同期
await fse.outputFile('async.txt', 'hello');

// 同期
fse.outputFileSync('sync.txt', 'hello');

この設計により、コードの可読性と保守性が向上します。特に、CI スクリプトやビルドツール、CLI ツールなど、ファイル操作が中心となる Node.js アプリケーションでは顕著です。

⚠️ 非推奨パッケージのリスク:fs-extra-promise について

fs-extra-promise は npm ページに以下の警告が記載されています:

This package is deprecated. fs-extra now includes promise support out of the box.

また、GitHub リポジトリもアーカイブされており、更新されていません。このパッケージを使うと、以下のような問題が発生します:

  • 不要な依存関係の追加
  • 将来的なセキュリティ脆弱性への対応なし
  • fs-extra の最新機能(例:move()、emptyDir() など)が利用できない可能性

したがって、新規プロジェクトでは絶対に使用しないでください。

🛠️ 実用的な使用例比較

シナリオ:設定ファイルの読み込みとフォールバック

アプリ起動時に config.local.json を読み、存在しなければ config.default.json を使う。

// fs + promises
const { promises: fsPromises } = require('fs');
async function loadConfig() {
  try {
    return JSON.parse(await fsPromises.readFile('config.local.json', 'utf8'));
  } catch (err) {
    if (err.code === 'ENOENT') {
      return JSON.parse(await fsPromises.readFile('config.default.json', 'utf8'));
    }
    throw err;
  }
}
// fs-extra
const fse = require('fs-extra');
async function loadConfig() {
  if (await fse.pathExists('config.local.json')) {
    return fse.readJson('config.local.json');
  }
  return fse.readJson('config.default.json');
}

fs-extra の readJson() と pathExists() により、コードが簡潔で意図が明確になります。

シナリオ:ビルドディレクトリのクリーンアップと再生成

// fs-extra
const fse = require('fs-extra');
await fse.emptyDir('dist');
await fse.copy('public', 'dist');
await fse.writeJson('dist/manifest.json', { version: '1.0.0' });

このようなタスクを fs だけで実装すると、エラーハンドリングや再帰処理のロジックを自前で書く必要があり、冗長かつ脆弱になります。

📊 まとめ:どのパッケージを選ぶべきか?

パッケージPromise 対応高度なユーティリティメンテナンス状況推奨用途
fs✅(.promises 経由)❌✅(Node.js 標準)軽量なスクリプト、最小限の依存を求める場合
fs-extra✅(ネイティブ)✅✅ほとんどの Node.js プロジェクト(CLI、ビルドツール、サーバーなど)
fs-extra-promise✅(ラップ)✅(fs-extra 依存)❌(非推奨)使用禁止

💡 最終的なアドバイス

  • 新規プロジェクトでは、ほぼ常に fs-extra を選ぶべきです。API が直感的で、よく使うファイル操作が一発で実現できます。
  • 極めて軽量な環境(例:Docker コンテナで依存を最小化したい)や、Node.js 標準モジュールのみを使いたいポリシーがある場合に限り、fs を検討してください。
  • fs-extra-promise は過去の遺物です。もし既存コードに含まれていたら、早急に fs-extra に移行しましょう。

ファイルシステム操作は Node.js アプリの根幹を成す部分です。正しいツールを選ぶことで、コードの信頼性と開発速度を大きく向上させることができます。

選び方: fs vs fs-extra vs fs-extra-promise

  • fs:

    fs は Node.js 標準のモジュールであり、外部依存を一切持ちたくない軽量なスクリプトや、極めてシンプルなファイル操作のみを行うケースに適しています。ただし、高度な操作(例:ディレクトリの再帰的コピー)には対応しておらず、Promise を使うには fs.promises サブモジュールを明示的にインポートする必要があります。依存関係を最小限に抑えたい環境や、Node.js の組み込み機能に厳密に依存したいポリシーがある場合に選択してください。

  • fs-extra:

    fs-extra は、ほとんどの Node.js プロジェクトで推奨される選択肢です。fs のすべての機能を包含しつつ、copy()、remove()、readJson() などの高レベルなユーティリティメソッドを提供し、すべての非同期メソッドが Promise を返すため async/await と自然に連携できます。CLI ツール、ビルドスクリプト、サーバーサイドアプリケーションなど、ファイル操作が中心となる開発において、コードの可読性と保守性を大幅に向上させます。

  • fs-extra-promise:

    fs-extra-promise は公式に非推奨(deprecated)とされており、新規プロジェクトでの使用は絶対に避けてください。fs-extra がバージョン 1.0.0 以降でネイティブに Promise をサポートするようになったため、このパッケージは不要となりました。既存コードに含まれている場合は、速やかに fs-extra への移行を検討してください。

fs のREADME

Security holding package

This package name is not currently in use, but was formerly occupied by another package. To avoid malicious use, npm is hanging on to the package name, but loosely, and we'll probably give it to you if you want it.

You may adopt this package by contacting [email protected] and requesting the name.