blog.dopana

戻る

TypeScript で CLI ツールを作りました。自分のマシンでは完璧に動きます。次はそれをユーザーに渡したい — ところがそのユーザーには Node.js も Bun も、インストールする前提もありません。

bun build --compile が解決するのがまさにこの問題です。コマンド 1 つ、ファイル 1 つで、何も入っていないマシンでも動く結果が手に入ります。

bun build --compile ./cli.ts --outfile mycli
bash

本当にそれだけです。ただしこの 1 行の裏には実測した数値、実質的なトレードオフ、そして実際に踏める落とし穴があります。この記事はそれらのすべてを扱います。

[!NOTE] 以下のすべての数値と挙動は、Bun 1.4.3 / macOS arm64 (Apple Silicon) でローカルに実測したもので、他の記事から写したものではありません。コマンドはすべて再現できます。

「単一ファイル実行ファイル」とは何か (ELI5)#

友人に夕食を作って差し上げると想像してみてください。

  • 普通の方法: レシピ (あなたの .ts ファイル)、買い物リスト (package.json)、そして「まずスーパーに行ってから」という指示を渡します。相手には「ちゃんと動く台所 (Node.js か Bun)」と、インターネットと、時間が必要です。壊れうる要素が 3 つあります。
  • コンパイルする方法: あなたが料理ごと作り上げ、容器に密封して渡します。相手は開けて食べるだけ。台所も準備も買い物も不要です。

bun build --compile がその容器です。出力は ネイティブバイナリ で、中に 3 つのものが入っています。

  1. あなたのコード (バンドル済み、tree-shake 済み)
  2. import したすべての npm パッケージ
  3. JavaScriptCore を含む Bun ランタイムの完全なコピー
bun build --compileあなたのプロジェクト.ts と .js ファイルimport した npm パッケージHTML, CSS などのアセットBundler: resolve, bundle,tree-shakeBun ランタイム:JavaScriptCore とコアモジュール1 個のネイティブバイナリ対象マシンに何もインストール不要

重要な帰結があります。出力のサイズを決めるのはコードではなくランタイムです。 これは後で実測します。

基準点: コマンド 1 つで何ができるか#

cli.ts
#!/usr/bin/env bun
import { $ } from "bun";

const args = Bun.argv.slice(2);
console.log("args:", args);
console.log("bun version:", Bun.version);

if (args[0] === "pkg") {
  console.log((await $`echo bundled-ok`.text()).trim());
}
ts
bun build --compile ./cli.ts --outfile ./mycli
bash

Bun 1.4.3 / macOS arm64 での実測結果:

  [27ms]  bundle  1 modules
 [260ms] compile  ./mycli
text

そして:

$ ./mycli hello world
args: [ "hello", "world" ]
bun version: 1.4.3

$ ./mycli pkg
args: [ "pkg" ]
bun version: 1.4.3
bundled-ok
bash

ビルドは約 300 ms。結果は 67.6 MB のバイナリで、何も入っていないマシンで動きます。

気になる数字#

サイズ: ペイロードはランタイム#

ビルドフラグバイナリサイズ備考
--compile67.6 MB (70,862,450 bytes)macOS arm64 の基準値
--compile --minify67.6 MB完全に同一 — ランタイムと比較すれば、あなたのコードは誤差レベルです
--compile --minify --sourcemap --bytecode67.6 MBサイズは同じ。bytecode の注意点は後述

ここで --minify は何も縮小しません。これはバグではありません。アプリが 3 KB のソースなら、minify で節約できるのは 67.6 MB 中わずか 1 KB 程度。minify は数 MB の依存関係をバンドルするときに効きますが、この場面では、思っているようなレバーにはなりません。

[!TIP] バイナリサイズが問題なら、--minify は答えではありません。レバーはランタイムであり、--compile ビルドからそれを取り除くことはできません。ベースレイヤを共有する Docker イメージで配るか、npm に publish してユーザーのランタイムに任せましょう。

起動時間: 効果はアプリの規模に比例する#

同じマシン上で、各コマンドを 3 回ウォームアップしてから 20 回実行して計測しました。

コマンド1 回あたりの時間
node -e "console.log('x')"26.7 ms
bun run simple.ts (1 モジュール)6.9 ms
コンパイル済み (1 モジュール)6.1 ms
bun run index.ts (400 モジュール)15.7 ms
コンパイル済み (400 モジュール)9.6 ms

見出しだけを見ると本次活动の効果を oversell しやすいので、率直にお読みください。

  • 1 ファイルのスクリプトでは、コンパイルで節約できるのは約 0.8 ms。プロセス起動が支配的で、勝てる余地はほとんどありません。
  • 400 個のモジュールを持つアプリでは、6.1 ms 節約 — 起動時間で 39% 削減です。

理由は Bun のドキュメントの記述そのものです。通常の Bun は起動のたびにディスクからファイルを読み、パスを解決し、パースしてトランスパイルします。--compile はこのコストをビルド時点に移します。コードが多いほど、移すものが増えていきます。

[!WARNING] 「コンパイル済みバイナリは瞬時に起動する」という文句は、修飾詞なしで引用しないでください。正確な言い方はこうです。束ねたコードが多いほど、節約できる起動時間が大きい — そして些細なスクリプトでは差分はノイズの範囲です。

クロスコンパイル: 一度ビルドして、どこへでも配る#

Linux バイナリを作るのに Linux マシンは不要です。--target を渡すだけです。

# Linux x64 (多くのサーバー)
bun build --compile --target=bun-linux-x64 ./index.ts --outfile myapp

# Linux ARM64 (Graviton, Raspberry Pi)
bun build --compile --target=bun-linux-arm64 ./index.ts --outfile myapp

# Windows x64 / ARM64 (.exe は自動で付与される)
bun build --compile --target=bun-windows-x64 ./src/cli.ts --outfile myapp
bun build --compile --target=bun-windows-arm64 ./src/cli.ts --outfile myapp

# macOS
bun build --compile --target=bun-darwin-arm64 ./src/cli.ts --outfile myapp
bun build --compile --target=bun-darwin-x64 ./src/cli.ts --outfile myapp
bash

対応ターゲット:

--targetOSアーキテクチャlibc
bun-linux-x64Linuxx64glibc
bun-linux-arm64Linuxarm64glibc
bun-linux-x64-muslLinuxx64musl
bun-linux-arm64-muslLinuxarm64musl
bun-windows-x64Windowsx64—
bun-windows-arm64Windowsarm64—
bun-darwin-x64macOSx64—
bun-darwin-arm64macOSarm64—

Apple Silicon の Mac から Linux x64 へクロスコンパイルし、実際の ELF バイナリが得られることを確認しました。

bun build --compile --target=bun-linux-x64 ./cli.ts --outfile ./app-linux-x64

[3.482s] compile  ./app-linux-x64 bun-linux-x64-v1.4.3

$ file ./app-linux-x64
ELF 64-bit LSB executable, x86-64, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2
text

musl ターゲットは Alpine コンテナ向けのバイナリになります。

$ file ./app-musl
ELF 64-bit LSB executable, x86-64, dynamically linked, interpreter /lib/ld-musl-x86_64.so.1
text

[!NOTE] 初回のクロスコンパイルではターゲットのランタイムをダウンロードします (今回の計測で約 40 MB、所要時間 約 3.5 秒)。2 回目以降はキャッシュされるためビルドは速くなります。CI では ~/.bun/install/cache をキャッシュして、ジョブごとに再ダウンロードしないようにしてください。

挙動を変えるフラグ#

--define — ビルド時定数#

bun build --compile --define BUILD_VERSION='"1.2.3"' --define BUILD_TIME='"2024-01-15T10:30:00Z"' \
  src/cli.ts --outfile mycli
bash
console.log(BUILD_VERSION); // 1.2.3
console.log(typeof BUILD_VERSION); // string
ts

Bun はこれらをビルド時にインライン化するため、実行時コストはゼロで、デッドコードの除去が可能になります。

--sourcemap — 元のソースを指すスタックトレース#

コンパイル済みバイナリでは、思っていた以上に重要なオプションです。これがないとスタックトレースが仮想ファイルシステムを指してしまいます。

--sourcemap=linked ありの場合:

error: kaboom from original source
      at boom (crash.ts:2:9)
      at crash.ts:4:1
text

なしの場合:

error: kaboom from original source
      at boom (/$bunfs/root/crash2:4:9)
      at /$bunfs/root/crash2:6:5
text

同じバグ、同じメッセージ — ただ前者のみがどのファイルのどの行を開けばよいかを教えてくれます。配るものには常に --sourcemap を使ってください。

--bytecode — と top-level await のバグ#

--bytecode は JavaScriptCore のパース作業を実行時からビルド時へ移します。Bun 1.4.3 で再現可能な問題が見つかりました。

tla.ts
const v = await Promise.resolve(42);
console.log("tla:", v);
ts
$ bun build --compile --bytecode --outfile ./b-tla ./tla.ts
1 | const v = await Promise.resolve(42);
                    ^
error: "await" can only be used inside an "async" function
    at /private/tmp/bcompile/tla.ts:1:17

1 | const v = await Promise.resolve(42);
                           ^
error: Unexpected .
    at /private/tmp/bcompile/tla.ts:1:24
bash
$ bun build --compile --outfile ./b-tla-nobc ./tla.ts # 同じファイル、--bytecode なし
 [2ms]  bundle  1 modules
[171ms] compile  ./b-tla-nobc
$ ./b-tla-nobc
tla: 42
bash

つまり: top-level await と --bytecode の組み合わせはビルドできません (2 回中 2 回再現)。一方、同じファイルは --bytecode なしなら問題なくビルドして実行できます。top-level await のないスクリプトは --bytecode でも問題なくコンパイルされます。

[!WARNING] エントリポイントが top-level の await を使っている場合 (await Bun.$、await Bun.file(...)、あるいはトップレベルの fetch など、ごく普通に登場します)、Bun 1.4.3 では --bytecode を有効にしないでください。コンパイルできないビルドを配る前に、自分のエントリポイントを確認してください。

--compile-exec-argv — ランタイムフラグを埋め込む#

bun build --compile --compile-exec-argv="--smol --user-agent=MyBot" ./app.ts --outfile myapp
bash
console.log(process.execArgv); // ["--smol","--user-agent=MyBot"]
ts

再コンパイルせずに実行時にフラグを変更することもできます。環境変数 BUN_OPTIONS を使います。

BUN_OPTIONS="--cpu-prof" ./myapp
bash

bunfs の落とし穴 — 最も驚かされるもの#

コードがバイナリの中に入った時点で、ディスク上に src/ ディレクトリはもうありません。Bun は埋め込まれたファイルを 仮想ファイルシステム bunfs として公開し、/$bunfs/root にマウントされます。

コンパイル済みバイナリを実行してパスを出力しました。

import.meta.path: /$bunfs/root/mycli
import.meta.dir:  /$bunfs/root
execPath:         /private/tmp/bcompile/mycli
text

3 つの帰結があります。

  1. import.meta.path は実在するパスではありません。 自身の位置を基準にファイルを開くコードは壊れます。バイナリの実パスが必要な場合は process.execPath を使ってください。
  2. import.meta.dir は bunfs を指します。 埋め込まれたアセット を探すには正しい場所ですが、スクラッチファイルを書く場所ではありません。
  3. 埋め込まれたアセットは bunfs パスで参照します。 Bun はファイル名をハッシュ化するため、推測はできません。

埋め込みファイルの読み込み — import attribute が重要#

assets.ts
import assetPath from "./asset.txt" with { type: "file" };
import readmeText from "./README.txt" with { type: "text" };
ts

ここが 別の 2 ファイル になっている点に注目してください。偶然ではなく、下の警告にその理由があります。

この 2 行は 相互に置き換えられません。

// { type: "file" } → パスが得られる。内容ではない
console.log(assetPath);                       // "/$bunfs/root/asset-b45kncad.txt"
console.log(await Bun.file(assetPath).text()); // "embedded-asset-content"

// { type: "text" } → 内容が直接得られる
console.log(readmeText);                      // "Hello from README"
ts

埋め込まれたファイルをすべて列挙したい場合は Bun.embeddedFiles を使います。これは Blob オブジェクトの配列です。

for (const blob of Bun.embeddedFiles) {
  console.log(blob.size, blob.type);          // 23 text/plain;charset=utf-8
  console.log(await blob.text());             // "embedded-asset-content"
}
ts

[!TIP] type: "file" と type: "text" の区別は、ほぼ全員がつまずく点です。内容だけが必要なら type: "text" を使ってください。type: "file" は、実ファイルが必要な対象にパスを渡したい場合 (例: Bun.file()、Bun.serve()、ネイティブライブラリ) だけ使います。

同じファイルを 2 回 import しない#

もう 1 つ、細かい罠があります。同じファイルを異なる attribute 付きで 2 回 import すると、Bun はそれらを 1 つのモジュールにまとめます。そして 最初 の import の attribute が勝ち、両方の 変数に適用されます。

quirk.ts
// "text" の import が先 → どちらも内容
import a from "./asset.txt" with { type: "text" };
import b from "./asset.txt" with { type: "file" };
console.log(JSON.stringify([a, b])); // ["embedded-asset-content\n","embedded-asset-content\n"]

// "file" の import が先 → どちらもパス
import c from "./asset.txt" with { type: "file" };
import d from "./asset.txt" with { type: "text" };
console.log(JSON.stringify([c, d])); // ["/$bunfs/root/asset-b45kncad.txt","/$bunfs/root/asset-b45kncad.txt"]
ts

[!WARNING] Bun 1.4.3 での実測結果です。各ペアで 両方の 変数が同じ種類の値を受け取ります。パスか内容かは、先に来る import 的一方に従います。両方とも必要なら、そのアセットを 別々の 2 モジュール から import するか、Bun.embeddedFiles を走査してください。

フルスタックの実行ファイル#

--compile はフロントエンドのアセットもバンドルします。HTML を import すると、Bun はそれを、参照している CSS と JS とともに埋め込みます。

server.ts
import { serve } from "bun";
import index from "./index.html";

const server = serve({
  routes: {
    "/": index,
    "/api/hello": { GET: () => Response.json({ message: "Hello from API" }) },
  },
});

console.log(`Server running at http://localhost:${server.port}`);
ts
bun build --compile ./server.ts --outfile myapp
bash

実行してみましょう — サーバーが起動し、ポートを割り当て、埋め込んだフロントエンドを正しい MIME タイプとキャッシュヘッダーで配信しました。ファイル 1 個でサーバーとクライアント、どこにでもデプロイできます。

あなたの CLI は Bun そのものになれる#

Bun 1.2.16 以降、実行ファイルは Bun CLI 自体にフォールバックできます。

BUN_BE_BUN=1 ./myapp install
bash

検証しました。通常実行では "you should not see this" と表示するスクリプトからビルドしたバイナリが、その文字列をそのまま表示し、BUN_BE_BUN=1 を設定すると実際の Bun バージョンを表示しました。これにより、パッケージのインストールや依存関係のバンドル、他のファイルの実行もできる CLI を、2 つ目のバイナリを配らずに提供できます。

npm 依存関係はどうなるの?#

バンドルされます。picocolors を import したスクリプトをコンパイルし、node_modules を別の場所へ移動してからバイナリを実行しました。

colored: hello-from-a-npm-package
text

それでも動作しました。バイナリは対象マシンで何も必要としません — 依存関係のディレクトリすら不要です。

コンパイルしてはいけない場合#

コンパイルは無料ではなく、常に正解ではありません。

エンドユーザー向け CLI ツールコンテナ内で動くサーバーユーザーが既に JS ランタイムを持つ制約のある Lambda で動かすBun のないマシンに配布する必要がありますか?はいbun build --compile1 ファイル、セットアップ不要Docker イメージを使う共有ベースレイヤは 67 MB のバイナリより勝ちnpm に publish最小のダウンロード、最小の更新先にサイズ予算を確認する67 MB は収まるがギリギリ

実践上の警告:

  • macOS Gatekeeper. インターネットからダウンロードした未署名のバイナリは隔離され、ユーザーが許可するまでブロックされます。署名済みバイナリを配るか、承認手順を案内してください。
  • Docker イメージ. 67 MB のバイナリを全レイヤーにコピーするとイメージのサイズが膨らみます。軽量なランタイムベースレイヤーが勝ることが多いです。
  • ネイティブアドオン. ビルドマシン向けにコンパイルされた .node アドオンは、やはりコンパイル済みバイナリです。クロスコンパイルはネイティブ C++ アドオンをクロスコンパイルしません。--target ビルドを CI 上で対象アーキテクチャのまま行うべき主な理由がこれです。
  • 频繁な更新. リリースごとに 67 MB のファイルを配るのは、npm に小さなパッケージを publish するより遅いです。

Bun.build() API#

上記はすべてプログラムからも使えます。ビルドスクリプトにちょうどよい形です。

build.ts
const result = await Bun.build({
  entrypoints: ["./cli.ts"],
  compile: {
    outfile: "./mycli",
    target: "bun-linux-x64",
  },
  define: {
    BUILD_VERSION: JSON.stringify("1.2.3"),
  },
  minify: true,
  sourcemap: "linked",
  bytecode: true,
});

console.log(result.success, result.outputs.length);
ts

TL;DR#

# 1 ファイル、どこでも動く
bun build --compile ./cli.ts --outfile mycli

# ノート PC 上でクロスコンパイル
bun build --compile --target=bun-linux-arm64 ./cli.ts --outfile mycli

# 実際に配る設定
bun build --compile --minify --sourcemap=linked ./cli.ts --outfile mycli
bash
  • macOS arm64 での出力は 67.6 MB — Bun ランタイムの部分であり、あなたのコードではありません。--minify で小さくなりません。
  • 起動時間の節約はコード量に比例します。1 ファイルスクリプトで 約 0.8 ms、400 モジュールのアプリで 6.1 ms (39%)。
  • コンパイル済みバイナリ内の import.meta.path は /$bunfs/root/<name> です。実パスには process.execPath を使ってください。
  • with { type: "file" } は パスを、with { type: "text" } は 内容を返します。
  • 同じアセットを 2 回 import しないでください — 最初の import の attribute が勝ち、両方の変数に適用されます。
  • エントリポイントが top-level await を使うなら --bytecode は避ける — Bun 1.4.3 ではビルドできません。
  • --sourcemap は必ず付けてください。無いとスタックトレースが /$bunfs/root を指し、ソースを指しません。

参考資料#