node:fs・node:path・node:url の Bun ネイティブ代替
node:fs、node:path、node:url から Bun.file()、Bun.write()、Bun.$ への実践的なマッピングと、Node のまま使い続けるべき場面の整理。
Node.js のコードベースがあります。問題なく動いている。チームが Bun を試したい理由は単純です。起動が速く、テストランナーがランタイムに内蔵され、依存関係のインストールが数分で終わります。
そして最初のファイルを開くと、こんなコードがあちこちにあります。
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
const configPath = path.join(__dirname, "config.json");
const raw = fs.readFileSync(configPath, "utf8");tsすぐに浮かぶ疑問はひとつです。「これって全部書き直さないといけないのか?」
結論から言うと いいえ です。そしてこれが Bun の設計について理解しておくべき最も重要なポイントです。Bun は別の惑星ではありません。同じ惑星に、大きめの道具箱を提げただけの存在です。
10 秒で分かる答え#
| Node.js | Bun の代替 | 書き直すべきか? |
|---|---|---|
node:fs | Bun.file()、Bun.write()、Bun.$ | 中身の読み書きが単純な場合のみ |
node:path | path / node:path | いいえ — そのまま使えばOK |
node:url | URL、URLSearchParams(Web API) | 本当に Web API が欲しいときのみ |
node:child_process | Bun.$、Bun.spawn | 任意。シェル実行なら効果大 |
思考モデル: 道具箱が広いだけ、世界が違うわけではない#
このトピック全体を理解するには、簡単な比喩を一つ覚えるだけで十分です。
大工の工房を想像してください。Node.js は、锤子、鋸、ドライバーが入った道具ベルトを渡してくれます。そこに Bun が現れて、こう言います。「より良い锤子、電動鋏、レーザー測距器を用意しました。ついでに、古い锤子もそのまま使えますよ」
新しい道具が使えるようになったからって、古い道具を捨てなくてよいのです。選択肢が増えただけなので、新しい道具が本当にコードを読みやすくするときに使えばよいのです。
Bun の互換レイヤーは意図的に厚く実装されています。node:fs、node:path、node:url、node:http をはじめ、数百のモジュールが Node とまったく同じセマンティクスで動きます。それが Bun の存在意義であり、既存の Node コードの 大半はそのまま動かせる からです。
[!TIP] Bun ネイティブ API は 移行の義務 ではなく アップグレードの手段 として考えましょう。ファイル単位で、コードが読みやすくなったタイミングで適用できます。
1. node:fs → Bun.file() と Bun.write()#
基本的な置き換え#
// Node
import fs from "node:fs";
const text = fs.readFileSync("file.txt", "utf8");
fs.writeFileSync("file.txt", "hello");ts// Bun
const text = await Bun.file("file.txt").text();
await Bun.write("file.txt", "hello");ts考え方はそれだけです。Bun.file(path) は ファイルハンドル(厳密には Web 標準の Blob インターフェースを実装した BunFile)を返し、Bun.write(destination, data) は任意のデータをディスクに書き出します。
存在確認#
const exists = await Bun.file("file.txt").exists();tsNode での try { fs.accessSync(p) } catch { false } という妙なイディオムよりずっと読みやすいはずです。
[!WARNING]
Bun.file()は 遅延評価(lazy) です。ハンドルを作っただけではディスクに触れず、ファイルが存在しなくても例外は投げません。存在しないファイルのsizeは0、typeは"text/plain;charset=utf-8"になります。エラーが現れるのは実際に読み込んだときだけです(ENOENT: no such file or directory)。存在確認がしたいなら.exists()を使い、Bun.file()を検証手段として使わないでください。
JSON を読む#
const data = await Bun.file("config.json").json();tsJSON.parse(fs.readFileSync(...)) という定型句が不要になります。.json() が解析済みオブジェクトを返します。
BunFile でできること#
const file = Bun.file("data.bin");
await file.text(); // string
await file.json(); // パース済み JSON
await file.arrayBuffer(); // ArrayBuffer
await file.bytes(); // Uint8Array
file.stream(); // ReadableStream
await file.exists(); // boolean
await file.delete(); // ファイルを削除tsBunFile は そのまま Blob なので、fetch や Response、バイナリを受け取る API にそのまま渡せます。
書き込み#
Bun.write() は万能ツールです。宛先はパス、file:// URL、BunFile のいずれでもよく、荷物は string、Blob、ArrayBuffer、TypedArray,甚至 Response のボディでも構いません。
await Bun.write("output.txt", "plain text");
await Bun.write("output.txt", new Uint8Array([1, 2, 3]));
// ファイルコピー — Bun がプラットフォームごとに最速の syscall を選びます
await Bun.write(Bun.file("copy.txt"), Bun.file("input.txt"));
// そのままディスクへダウンロード
const response = await fetch("https://bun.com");
await Bun.write("index.html", response);
// ファイルの中身を stdout へ
await Bun.write(Bun.stdout, Bun.file("input.txt"));tsBun.write() は 書き込んだバイト数 を返すので、ログ用途にも便利です。
const bytes = await Bun.write("output.txt", "hello");
console.log(`wrote ${bytes} bytes`); // wrote 5 bytestsFileSink による段階的書き込み#
ファイルが大きすぎてメモリに載り切らない場合は writer を使います。
const writer = Bun.file("output.txt").writer();
writer.write("it was the best of times\n");
writer.write("it was the worst of times\n");
await writer.end(); // flush してクローズts[!NOTE] 挙動の違いが一つだけ覚えておいてください。
Bun.write()は親ディレクトリが無い場合は自動作成します。一方 Node のfs.writeFileSync()は親ディレクトリが無いとENOENTを投げます。Bun 1.4.3 で検証済み —Bun.write("a/b/c.txt", "x")は成功し、a/b/も作られます。
node:fs が引き続き担当する領域#
Bun.file() が扱うのは ファイルの中身 です。ファイルシステムそのもの ではありません。次の操作は node:fs のままにしましょう。Bun の実装は十分高速です。
import { mkdir, readdir, stat } from "node:fs/promises";
// ディレクトリツリーの作成
await mkdir("build/output", { recursive: true });
// ファイル一覧
const entries = await readdir(import.meta.dir, { recursive: true });
// メタデータ
const info = await stat("package.json");
console.log(info.size, info.mtime);tsBun の公式ドキュメントにもこう書かれています。for operations they don’t cover, such as mkdir or readdir, use Bun’s nearly complete implementation of the node:fs module.
シェル実行の脱出ハッチ: Bun.$#
ファイル I/O だけがあなたのコードの I/O ではありません。コマンドを実行したい場合もあります。
// Node
import { execSync } from "node:child_process";
execSync("git rev-parse HEAD");ts// Bun
import { $ } from "bun";
const hash = await $`git rev-parse HEAD`.text();tsBun.$ は Rust で書かれた、クロスプラットフォームな bash 風シェルです。/bin/sh を呼び出すラッパーではなく、Bun プロセス内で動く再実装なので、Windows でも macOS でも Linux でも同じ挙動になります。
await $`ls -la`.quiet(); // 出力なし
await $`echo "hi"`.text(); // "hi\n"
await $`cat package.json`.json(); // パース済み JSON
for await (const line of $`cat list.txt`.lines()) { /* ... */ }tsセキュリティ上重要な点がひとつ。補間された値はデフォルトでエスケープされます。ユーザー入力をコマンドに注入できません。
const userInput = "my-file.txt; rm -rf /";
await $`ls ${userInput}`; // ls は 2 つのコマンドではなく、1 つのリテラル引数を受け取りますtsプロセスの完全な制御(stdin/stdout のパイプ、環境変数、終了コード)が必要なら Bun.spawn を使います。
const proc = Bun.spawn(["echo", "hello"], { stdout: "pipe" });
const output = await new Response(proc.stdout).text();
await proc.exited;
console.log(output, proc.exitCode);ts2. node:path → そのまま使い続ける#
import path from "node:path";
const file = path.join("src", "index.ts");
const dir = path.dirname(file);
const ext = path.extname(file);
const abs = path.resolve(file);tsBun で node:path を置き換える利点はありません。
- 単なる文字列処理で、I/O もランタイムの黒魔法もありません。
- プラットフォームを認識します(Windows の区切り文字、ドライブ文字、UNC パス)。
- Bun は完全に実装しており、Node 自身のテストスイートも 통과しています。
- 手作業で文字列連結に置き換えるのは ダウングレード であり、アップグレードではありません。
Bun 固有の便利さがひとつだけあります。このファイルがどこにあるか をそのまま取得できることです。
import.meta.dir; // "/a/b" — このファイルのディレクトリ(絶対パス)
import.meta.path; // "/a/b/c.ts" — このファイル(絶対パス)tsprocess.cwd()(コマンドを実行した場所)とは対比してください。import.meta.dir は Bun における「モジュールと同じ場所にあるファイルを探す」という古典的な問題への答えです。
[!NOTE] Node.js も追いつきました。Node 20.11 / 21.2 以降、
import.meta.dirnameとimport.meta.filenameは標準になりました。両方のランタイムで動かしたいコードならimport.meta.dirnameの綴りが移植可能で、import.meta.dirは Bun 専用です。
3. node:url → 標準の Web API を優先する#
URL クラスは Bun の発明ではありません。ブラウザ、Node、Deno、Bun、Worker、どこにでも存在する Web 標準です。
const url = new URL("https://example.com/foo?bar=baz");
console.log(url.pathname); // "/foo"
console.log(url.searchParams.get("bar")); // "baz"
console.log(url.host); // "example.com"tsクエリ文字列を組み立てるには URLSearchParams が一番素直で扱いやすいです。
const params = new URLSearchParams({ page: "2", q: "bun runtime" });
console.log(`https://api.example.com/search?${params}`);ts「モジュールの URL をディスク上のパスに変換する」という非常によくあるケースでは、Node はヘルパーが必要です。
import { fileURLToPath } from "node:url";
const filename = fileURLToPath(import.meta.url);tsBun では通常ヘルパーすら不要です。
const filename = import.meta.path;
const dirname = import.meta.dir;tsfileURLToPath() は Bun でも(node:url 経由で)動作します。import.meta.url だけでなく 任意の file:// URL を変換するときが、正しい用途です。
const localPath = fileURLToPath(new URL("../config/app.json", import.meta.url));ts書き直すべきかの判断フロー#
痛くない移行手順#
- まずは何もしない。 Dockerfile や CI の
nodeをbunに変えてテストを回すだけ。ほとんどのコードはそのまま通ります。 - ロジックではなく、定型句を入れ替える。
fs.readFileSync+JSON.parseをawait Bun.file(p).json()に置き換える。これは可読性の向上であって、書き直しではありません。 execSyncの文字列になっているシェル実行にはBun.$を導入する。 エスケープとクロスプラットフォーム挙動が無料で得られます。- 本当に Web の
URLAPI が欲しい場合を除いて、node:pathとnode:urlには触れない。 - ディレクトリと権限の操作は
node:fsのまま。 Bun のnode:fsは高速で、なくなる予定もありません。
覚えておきたい落とし穴#
Bun.file()はファイルが存在しなくても例外を投げません。それは 約束 であり 検査 ではありません。.exists()を使ってください。Bun.write()はバイト数を返し、親ディレクトリが無い場合は自動作成します。Bun.file()はパス、ファイルディスクリプタ、file://URL を受け取ります:Bun.file(new URL(import.meta.url))。import.meta.path/import.meta.dirは Bun 専用。移植可能なのはimport.meta.urlです。node:fsの同期 API も Bun で問題なく動きますし高速です。「すべて async」はスタイル選択であって要件ではありません。- ディレクトリに対して
Bun.file()を使わないでください。ファイルの中身専用です。
TL;DR#
目的が Bun 互換性 なら、すべてを書き直す必要はありません。
node:fs → Bun ネイティブ API が欲しいときは Bun.file / Bun.write
node:path → node:path のまま使う
node:url → URL / URLSearchParams、または必要なら node:url のままtextBun は大量の既存 Node.js コードを変更せずに動かせるように設計されています。コードが読みやすくなる場所で Bun ネイティブ API を使い、残りはそのままにしておきましょう。
参考資料#
- Bun Documentation — File I/O ↗
- Bun Documentation — Shell ↗
- Bun Documentation — Node.js Compatibility ↗
- Bun Documentation —
import.meta.dir↗ - Bun API Reference —
Bun.write()↗ - Node.js Documentation —
node:path↗ - Node.js Documentation —
node:url↗ - Node.js Documentation —
import.meta.dirname↗ - MDN —
URL↗