fs、fs-extra、fs-extra-promise はいずれも Node.js におけるファイルシステム操作を目的としたパッケージですが、その機能範囲と非同期処理への対応に大きな違いがあります。fs は Node.js 標準のモジュールで基本的なファイル操作を提供します。fs-extra は fs を拡張し、再帰的なコピー・削除などの高レベルなユーティリティと、Promise ベースの API をネイティブにサポートします。一方、fs-extra-promise はかつて fs-extra の Promise 対応を補助するラッパーとして存在しましたが、現在は非推奨となっており、新規プロジェクトでの使用は推奨されません。
fs vs fs-extra vs fs-extra-promiseNode.js でファイルやディレクトリを扱う際、標準の fs モジュールから始まり、より高機能な代替手段として fs-extra やその派生パッケージが登場してきました。しかし、これら3つの選択肢には明確な違いと適切な使用場面があります。特に、現代の非同期処理への対応や API の使いやすさという点で大きな差が出ます。以下では、実際の開発現場での判断材料になるよう、技術的観点から深く比較します。
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 が直感的で、よく使うファイル操作が一発で実現できます。fs を検討してください。fs-extra-promise は過去の遺物です。もし既存コードに含まれていたら、早急に fs-extra に移行しましょう。ファイルシステム操作は Node.js アプリの根幹を成す部分です。正しいツールを選ぶことで、コードの信頼性と開発速度を大きく向上させることができます。
fs は Node.js 標準のモジュールであり、外部依存を一切持ちたくない軽量なスクリプトや、極めてシンプルなファイル操作のみを行うケースに適しています。ただし、高度な操作(例:ディレクトリの再帰的コピー)には対応しておらず、Promise を使うには fs.promises サブモジュールを明示的にインポートする必要があります。依存関係を最小限に抑えたい環境や、Node.js の組み込み機能に厳密に依存したいポリシーがある場合に選択してください。
fs-extra は、ほとんどの Node.js プロジェクトで推奨される選択肢です。fs のすべての機能を包含しつつ、copy()、remove()、readJson() などの高レベルなユーティリティメソッドを提供し、すべての非同期メソッドが Promise を返すため async/await と自然に連携できます。CLI ツール、ビルドスクリプト、サーバーサイドアプリケーションなど、ファイル操作が中心となる開発において、コードの可読性と保守性を大幅に向上させます。
fs-extra-promise は公式に非推奨(deprecated)とされており、新規プロジェクトでの使用は絶対に避けてください。fs-extra がバージョン 1.0.0 以降でネイティブに Promise をサポートするようになったため、このパッケージは不要となりました。既存コードに含まれている場合は、速やかに fs-extra への移行を検討してください。
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.