BunでCLIツールを作成してシングルバイナリ化するメモ

こんにちは。

最近、Node.jsの代わりに Bun を使ってCLIツールを作ってみたのですが、起動速度が速く、シングルバイナリ化も非常に簡単でした。
その際の手順やポイントを、備忘録として残しておきます。

作ったものについて

一言で言うと、「TypeScriptで書いた処理を、Bunなしで動くバイナリとして配布できるCLIツール」 です。

通常、Node.jsでCLIツールを作ると「トランスパイルが必要」「ユーザーにもNode.js環境が必要」「起動がもっさりする」といった課題がありますが、Bunを使うことでこれらを一気に解消できます。

BunでCLIを作る手順

Step 0: Bunのインストール

まずはBun本体をインストールします。
OSによってコマンドが異なりますが、以下のコマンド一発で入ります。

macOS / Linux / WSL:

curl -fsSL [https://bun.sh/install](https://bun.sh/install) | bash

Windows (PowerShell):

powershell -c "irm bun.sh/install.ps1 | iex"

インストールが終わったら、パスを通してからバージョンを確認します。

bun --version
# 1.1.x などが表示されればOK

Step 1: プロジェクトの初期化

まずはプロジェクトを作成します。
bun init を実行するだけで、TypeScriptの環境が即座に整います。

mkdir bun-cli-memo
cd bun-cli-memo
bun init

Step 2: 実装 (Shebangが重要)

index.ts に処理を書きます。
ここで重要なのは、ファイルの先頭に Shebang (シバン) を記述することです。

index.ts

#!/usr/bin/env bun

const main = () => {
  const args = Bun.argv.slice(2);
  const name = args[0] || "Guest";

  console.log(`Hello, ${name}! Bun is running 🚀`);
};

main();

Step 3: シングルバイナリへのコンパイル

ここが一番のポイントです。
bun build コマンドを使って、ソースコードを単一の実行ファイルにコンパイルします。

bun build --compile --minify --sourcemap ./index.ts --outfile mycli

これで mycli というバイナリが生成されます。

ここまでのポイントまとめ

ざっくりまとめると以下のとおりです。

項目	説明
#!/usr/bin/env bun	スクリプトとして実行するために必須のShebang
bun build --compile	シングルバイナリを生成するコマンド
--minify	ファイルサイズを削減するためのオプション

よく使う引数パース処理 (util.parseArgs)

事象

CLIツールを作る際、引数の処理（例: --verbose や --name）をどうするか悩みます。
外部ライブラリ（Commander等）を入れるとサイズが大きくなることがありますが、Bun（Node.js互換）の標準機能だけで解決できます。

対処法

util モジュールの parseArgs を使用します。

index.ts

import { parseArgs } from "util";

const { values, positionals } = parseArgs({
  args: Bun.argv,
  options: {
    verbose: { type: 'boolean', short: 'v' },
    name: { type: 'string', short: 'n' },
  },
  strict: true,
  allowPositionals: true,
});

if (values.verbose) console.log("Debug mode enabled");
console.log(`Hello, ${values.name || "User"}!`);

ここまでのポイントまとめ

プロパティ名	説明
args	パース対象の引数 (Bun.argv を渡す)
options	フラグの設定（型やショートハンドを定義）
strict	定義されていない引数が渡された場合にエラーにするか

まとめ

• bun init だけでTS環境が手に入る！
• bun build --compile で配布が圧倒的に楽になる！
• 標準の parseArgs で依存関係を減らせる！

CLIツールの作成において、Bunは非常に強力な選択肢だと感じました。