blog.dopana

戻る

Node.js のコードベースがあります。問題なく動いている。チームが Bun を試したい理由は単純です。起動が速く、テストランナーがランタイムに内蔵され、依存関係のインストールが数分で終わります。

そして最初のファイルを開くと、こんなコードがあちこちにあります。

src/config.ts
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.jsBun の代替書き直すべきか?
node:fsBun.file()、Bun.write()、Bun.$中身の読み書きが単純な場合のみ
node:pathpath / node:pathいいえ — そのまま使えばOK
node:urlURL、URLSearchParams(Web API)本当に Web API が欲しいときのみ
node:child_processBun.$、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.js
// Node
import fs from "node:fs";

const text = fs.readFileSync("file.txt", "utf8");
fs.writeFileSync("file.txt", "hello");
ts
Bun
// 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();
ts

Node での 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();
ts

JSON.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();       // ファイルを削除
ts

BunFile は そのまま 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"));
ts

Bun.write() は 書き込んだバイト数 を返すので、ログ用途にも便利です。

const bytes = await Bun.write("output.txt", "hello");
console.log(`wrote ${bytes} bytes`); // wrote 5 bytes
ts

FileSink による段階的書き込み#

ファイルが大きすぎてメモリに載り切らない場合は 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 の実装は十分高速です。

src/scan.ts
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);
ts

Bun の公式ドキュメントにもこう書かれています。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.js
// Node
import { execSync } from "node:child_process";
execSync("git rev-parse HEAD");
ts
Bun
// Bun
import { $ } from "bun";

const hash = await $`git rev-parse HEAD`.text();
ts

Bun.$ は 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);
ts

2. 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);
ts

Bun で node:path を置き換える利点はありません。

  • 単なる文字列処理で、I/O もランタイムの黒魔法もありません。
  • プラットフォームを認識します(Windows の区切り文字、ドライブ文字、UNC パス)。
  • Bun は完全に実装しており、Node 自身のテストスイートも 통과しています。
  • 手作業で文字列連結に置き換えるのは ダウングレード であり、アップグレードではありません。

Bun 固有の便利さがひとつだけあります。このファイルがどこにあるか をそのまま取得できることです。

import.meta.dir;  // "/a/b"      — このファイルのディレクトリ(絶対パス)
import.meta.path; // "/a/b/c.ts" — このファイル(絶対パス)
ts

process.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 はヘルパーが必要です。

Node.js
import { fileURLToPath } from "node:url";

const filename = fileURLToPath(import.meta.url);
ts

Bun では通常ヘルパーすら不要です。

Bun
const filename = import.meta.path;
const dirname = import.meta.dir;
ts

fileURLToPath() は Bun でも(node:url 経由で)動作します。import.meta.url だけでなく 任意の file:// URL を変換するときが、正しい用途です。

const localPath = fileURLToPath(new URL("../config/app.json", import.meta.url));
ts

書き直すべきかの判断フロー#

node:fsはいいいえ: ディレクトリ、権限、シンボリックリンクnode:pathnode:urlはいいいえ: モジュールのパスBun プロジェクトで node: モジュールを import したどのモジュール?ファイルの中身の読み書きだけ?Bun.file() と Bun.write() を使うnode:fs のままにするnode:path のままにする書き直す利点はないWeb の URL API が必要?URL と URLSearchParams を使うimport.meta.path とimport.meta.dir を使う

痛くない移行手順#

  1. まずは何もしない。 Dockerfile や CI の node を bun に変えてテストを回すだけ。ほとんどのコードはそのまま通ります。
  2. ロジックではなく、定型句を入れ替える。 fs.readFileSync + JSON.parse を await Bun.file(p).json() に置き換える。これは可読性の向上であって、書き直しではありません。
  3. execSync の文字列になっているシェル実行には Bun.$ を導入する。 エスケープとクロスプラットフォーム挙動が無料で得られます。
  4. 本当に Web の URL API が欲しい場合を除いて、node:path と node:url には触れない。
  5. ディレクトリと権限の操作は 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 のまま
text

Bun は大量の既存 Node.js コードを変更せずに動かせるように設計されています。コードが読みやすくなる場所で Bun ネイティブ API を使い、残りはそのままにしておきましょう。

参考資料#