Blog

Bun API 入門

Mark Ponomarev

Mark Ponomarev

18 7月 2025

Bun API 入門

Apidog エンタープライズ

オンプレミスデプロイ

SSO & RBAC

SOC 2 準拠

Apidog Enterpriseを見る

最近の最も注目すべき開発ツールの一つにBunがあります。これは驚くほど高速で、開発者の生産性とアプリケーションのパフォーマンスを向上させるために設計されたオールインワンのJavaScriptツールキットです。Bunは単なる別のランタイムではありません。ランタイム、バンドラー、テストランナー、パッケージマネージャーなど、すべてを単一のネイティブ実行可能ファイルに統合した、まとまりのあるエコシステムです。このガイドでは、Bunの基本を、そのコアコンセプトと強力なAPIに焦点を当てて解説します。

💡
美しいAPIドキュメントを生成する優れたAPIテストツールをお探しですか？

開発チームが最大限の生産性で連携できる統合されたオールインワンプラットフォームをお探しですか？

Apidogはこれらのニーズをすべて満たし、Postmanをはるかに手頃な価格で置き換えます！
ダウンロード

Bunとは？

「Bunは高速なオールインワンJavaScriptランタイムです」というテキストが入ったBunのロゴ

その核となるのは、高性能なJavaScriptランタイムエンジンです。GoogleのV8エンジンを使用するNode.jsとは異なり、BunはSafariを動かすエンジンであるAppleのJavaScriptCore (JSC) を利用しています。この選択は、低レベルプログラミング言語であるZigでのBunの実装と相まって、その驚異的な速度に大きく貢献しています。Bunアプリケーションの起動時間は、同等のNode.jsアプリケーションよりも大幅に高速であることが多く、時には4倍以上になることもあります。この速度の利点は起動時だけにとどまりません。Bunの様々なAPIの内部実装は、最大限のスループットと最小限のメモリ使用量のために最適化されています。

しかし、Bunの野心は単に高速なランタイムであることにとどまりません。開発者の一般的なニーズに直接応える、包括的なツールキットを目指しています。

  1. 統合されたツール: bun コマンド自体が、多数の機能への入り口として機能します。bun run は package.json で定義されたスクリプトを実行し、bun install は依存関係を管理し（npmやyarnよりもはるかに高速なことが多い）、bun test はJest互換APIを使用してテストを実行し、bun build は本番用のコードをバンドルし、bunx はパッケージを明示的にインストールせずに実行します。この統合により、必要な開発ツールの数を減らし、ワークフローを簡素化します。
  2. ネイティブTypeScriptおよびJSXサポート: Bunの際立った機能の一つは、TypeScript (.ts, .tsx) および JSX (.jsx) ファイルに対する標準でのサポートです。Bunには、これらのファイルタイプを実行時またはバンドル時にシームレスに処理する、組み込みの高度に最適化されたトランスパイラーが含まれています。これにより、多くの一般的な開発シナリオで tsc や Babel を含む別途コンパイルステップが不要になり、セットアッププロセスが効率化されます。
  3. モジュールシステムの互換性: Bunは、ES Modules (ESM) のファーストクラスサポートにより、モダンJavaScriptを受け入れています。しかし、CommonJS (CJS) 上に構築された膨大な既存のエコシステムも認識しています。Bunは両方のモジュールシステムに対して堅牢な互換性を提供しており、開発者は import と require をほぼ互換的に使用し、npmで利用可能な数百万もの既存のCJSパッケージを活用できます。
  4. Web標準APIへの準拠: 重要な設計原則は、標準的なWeb APIの実装です。fetch、Request、Response、Headers、WebSocket、およびStreams API (ReadableStream、WritableStream) のような関数やオブジェクトは、Bunのグローバルスコープに組み込まれています。これにより、サーバーサイドのBun環境、ブラウザのフロントエンド、エッジコンピューティングプラットフォーム間でのコードの移植性が促進され、開発者は異なるコンテキストで使い慣れたAPIを再利用できます。
  5. Node.jsとの互換性: 最適化されたAPIとWeb標準で独自の道を切り開きながらも、BunはNode.js APIサーフェスとの高い互換性を目指しています。多くの組み込みNode.jsモジュール（node:fs、node:path、node:os、node:eventsなど）およびグローバルオブジェクト（process、Buffer、__filename、__dirname）は、部分的または完全に実装されています。目標は、多くの既存のNode.jsプロジェクトやnpmパッケージを最小限の変更または変更なしでBun上で実行できるようにし、多くの場合でBunを潜在的な「ドロップイン代替」として位置づけることです。

これらの要素を組み合わせることで、Bunはパフォーマンス、シンプルさ、モダンな開発体験を求めるJavaScriptおよびTypeScript開発者にとって魅力的な代替手段となります。

Bunのロゴ

Bunのインストール方法

Bunの利用開始は、様々なプラットフォームで迅速かつ簡単に行えるように設計されています。macOS、Linux、およびWindows Subsystem for Linux (WSL) で最も一般的な方法は、ターミナルで実行するシンプルな curl コマンドを使用することです。

curl -fsSL https://bun.sh/install | bash

このコマンドはインストールスクリプトをダウンロードし、それを直接 bash にパイプします。スクリプトはオペレーティングシステムとアーキテクチャの検出を処理し、適切なBun実行可能ファイルをダウンロードし、通常 ~/.bun/bin にインストールします。また、シェルの設定ファイル（`.zshrc`、`.bashrc`、`.bash_profile`など）を更新して、システム PATH に ~/.bun/bin を追加し、bun コマンドをグローバルに利用できるようにしようとします。変更をすぐに反映させるには、ターミナルセッションを再起動するか、シェルの設定ファイルを手動で読み込む（例: source ~/.zshrc）必要があるかもしれません。

パーミッションの問題が発生した場合や、bash に直接パイプしたくない場合は、まずスクリプトをダウンロードし、実行前に内容を確認できます。

curl -fsSL https://bun.sh/install -o install.sh
# Inspect install.sh if desired
bash install.sh

その他のインストール方法:

npm install -g bun

docker run --rm --init --ulimit memlock=-1:-1 oven/bun:latest bun --version

brew tap oven-sh/bun
brew install bun

確認:

インストールが完了したら、新しいターミナルウィンドウを開き、バージョンを確認してインストールを検証します。

bun --version

これによりインストールされたバージョン番号が出力され、Bunが使用可能であることが確認されます。また、bun --help を実行すると、利用可能なコマンドとオプションのリストが表示されます。

Bunを初めて実行する

Bunで簡単なプログラムを作成して実行してみましょう。最も一般的なタスクの一つは、HTTPサーバーを作成することです。Bunはこの目的のために、組み込みの高度に最適化されたAPIである Bun.serve を提供しています。

server.js (または server.ts、Bunは両方を扱えます) という名前で新しいファイルを作成します。

// server.ts

// Bun.serve は HTTP サーバーを開始します
const server = Bun.serve({
  // リッスンするポートを指定します。
  // デフォルトは process.env.PORT || 3000 です
  port: 3000,

  // 'fetch' 関数はコアとなるリクエストハンドラです。
  // 標準の Request オブジェクトを受け取り、Response オブジェクト（またはそれに解決される Promise）を返す必要があります。
  fetch(request: Request): Response {
    // 標準の Web API Response オブジェクトを作成します
    return new Response("Welcome to Bun!");
  },
});

// サーバーが実行中であることを示すメッセージをログに出力します
console.log(`Listening on http://localhost:${server.port}`);

このコードスニペットは以下のことを行います。

  1. BunでHTTPサーバーを作成するための主要な関数である Bun.serve を呼び出します。
  2. 設定オブジェクトを渡し、port（この場合は3000）を指定します。
  3. 重要な部分は fetch 関数です。この関数は、すべての着信HTTPリクエストに対して呼び出されます。Service Workerのfetchイベントハンドラーパターンに準拠しており、標準の Request オブジェクトを受け入れます。
  4. fetch の内部で、標準の Response オブジェクトを構築して返します。ここでは、単純にプレーンテキスト「Welcome to Bun!」を返します。
  5. 最後に、サーバーが実際にリッスンしているポート（server.port 経由でアクセス可能）を含む確認メッセージをコンソールにログ出力します。

このサーバーを実行するには、ファイルを保存したディレクトリでターミナルを開き、以下を実行します。

bun run server.ts

または、server.js として保存した場合は以下を実行します。

bun run server.js

Bunはスクリプトを実行します。TypeScript (server.ts) を使用した場合、Bunの内部トランスパイラーが実行前にオンザフライでJavaScriptへの変換を処理します。「Listening on http://localhost:3000」というメッセージが表示されるはずです。

次に、ウェブブラウザを開き、http://localhost:3000 にアクセスします。「Welcome to Bun!」というテキストが表示されるはずです。

サーバーを停止するには、ターミナルに戻り、Ctrl + C を押します。

この簡単な例は、基本的なサーバーをセットアップし、コード（TypeScriptを含む）をBunで直接実行することの容易さを示しており、その統合された性質と Request や Response のようなWeb標準APIへの依存を強調しています。

BunのネイティブTypeScriptサポートとは

特にすでにTypeScriptを使用している、または採用したい開発者にとって、Bunの最も重要な利点の一つは、そのファーストクラスで標準でのサポートです。TypeScriptを実行するために通常、TypeScriptコンパイラ（tsc）を使用した事前コンパイルや、ts-node や tsx のようなローダー/レジスターの使用が必要なNode.jsとは異なり、Bunはそれをネイティブかつ透過的に処理します。

仕組み:

Bunに .ts または .tsx ファイルを実行するように指示すると（例: bun run myscript.ts）、内部のトランスパイラーが自動的に起動されます。このトランスパイラーはネイティブコード（Zig）で書かれており、非常に高速です。その役割は以下の通りです。

  1. 型の削除: TypeScriptの型アノテーション、インターフェース、列挙型などを削除します。これらは標準的なJavaScript実行の一部ではないためです。
  2. 構文の変換: TypeScript固有の構文（特定の enum の使用法や、設定されている場合は古いデコレーター構文など）を同等のJavaScriptに変換します。
  3. JSXの処理: JSX構文（.tsx および .jsx ファイルで使用）を標準的なJavaScript関数呼び出し（通常は React.createElement または設定されたJSXランタイムの同等物）に変換します。

主な利点は、これが実行時（bun run）またはバンドル時（bun build）のプロセス中にオンザフライで行われることです。開発中にTypeScriptコードを実行するためだけに、別途明示的なビルドステップは必要ありません。

例:

このTypeScriptファイル（greet.ts）を考えてみましょう。

// greet.ts
interface User {
  name: string;
  id: number;
}

function greetUser(user: User): void {
  console.log(`Hello, ${user.name} (ID: ${user.id})!`);
}

const myUser: User = { name: "Bun Developer", id: 123 };

greetUser(myUser);

// Bunがサポートするモダンな機能も使用できます
const message = `Bun version: ${Bun.version}`;
console.log(message);

これを直接実行できます。

bun run greet.ts

Bunはこれを内部でトランスパイルし、結果のJavaScriptを実行して、以下のような出力を生成します。

Hello, Bun Developer (ID: 123)!
Bun version: 1.x.y

JSXサポート:

同様に、JSXを含む .tsx ファイルがある場合です。

// component.tsx

// JSXが設定されていると仮定します (BunのデフォルトはしばしばReactで機能します)
function MyComponent({ name }: { name: string }) {
  return <div className="greeting">Hello, {name}!</div>;
}

// 注意: これを直接実行してもHTMLはレンダリングされません、
// トランスパイルされたJS構造を示すだけです。
// 通常、より大きなアプリケーションやフレームワーク内でこれを使用します。
console.log("Simulating component creation (transpiled output structure):");
// 実際の出力はJSX変換設定に依存しますが、
// JavaScriptオブジェクト/関数呼び出しになります。

bun run component.tsx を実行するとファイルが実行され、JSXがJavaScriptにトランスパイルされます。

設定（tsconfig.json）:

Bunは、トランスパイルに影響する設定オプションのために tsconfig.json ファイルを尊重します。tsc のように完全な型チェックは行いませんが（Bunは実行とトランスパイルの速度に焦点を当てています）、tsconfig.json を読み取って以下のような設定を理解します。

tsconfig.json が見つからない場合、Bunは適切なデフォルト設定を使用します。

このシームレスな統合により、BunでのTypeScriptプロジェクト開始が信じられないほど簡単かつ高速になり、参入障壁を下げ、開発サイクルを加速させます。

Bun固有のAPIについて

BunはWeb標準APIおよびNode.jsとの互換性を強く強調していますが、グローバルな Bun オブジェクトの下に、独自の最適化された組み込みAPIのセットも導入しています。これらのAPIは、Bunのネイティブコード機能を活用する一般的なタスクに対して、高性能な代替手段または便利なラッパーを提供することがよくあります。

いくつかの主要な Bun.* APIを以下に示します。

これらのAPIは、Bunが一般的な開発タスクに対して最適化された組み込みソリューションを提供し、外部依存関係への依存を減らし、ネイティブコアの速度を活用しようとする取り組みを表しています。

BunにおけるWeb API

Bunにおける基本的な設計選択の一つは、標準的なWeb APIの実装への強いコミットメントです。特定のタスク（特にネットワーキングとデータ処理）に対して標準APIが存在する場合、Bunは独自のAPIを発明したり、Node.jsの慣習にのみ依存したりするのではなく、その標準を実装することを好みます。

このアプローチにはいくつかの重要な利点があります。

  1. コードの移植性: 標準Web APIを使用して書かれたコードは、ブラウザ、Node.js（これもWeb標準の採用が進んでいます）、Deno、Cloudflare Workers、Bunなど、異なるJavaScript環境間で少ない変更で再利用できることがよくあります。
  2. 親しみやすさ: ブラウザAPIにすでに慣れている開発者は、Bunを扱う際にその知識を活用でき、学習曲線が軽減されます。
  3. 将来性: WHATWGやW3Cのような団体によって確立された標準に合わせることは、長期的にはより安定し、広くサポートされるAPIにつながります。
  4. パフォーマンス: これらのWeb APIのBunのネイティブ実装は、そのランタイムのために高度に最適化されています。

Bunに実装されている主要なWeb標準APIには以下が含まれます。

Fetch API:

URL API:

Streams API:

Encoding API:

Blob API:

FormData API:

WebSocket API:

タイマー:

Console API:

Crypto API:

Performance API:

これらの必須Web APIの堅牢で高性能な実装を提供することで、Bunは使い慣れた標準化されたインターフェースを使用して、ウェブサーバー、API、その他のネットワーク中心のアプリケーションを構築するのに適したモダンなランタイムとして位置づけられています。

Bun HTTPサーバー解説

Bunでウェブサーバーを作成する主な方法は、Bun.serve APIを使用することです。これは優れたパフォーマンスと使いやすさのために設計されており、Request、Response、fetch のような標準Web APIとシームレスに統合されています。

コアコンセプト:

Bun.serve 関数は設定オブジェクトを受け取り、Server オブジェクトを返します。設定の最も重要な部分は fetch 関数です。

import { type Server } from "bun";

const server: Server = Bun.serve({
  port: 8080, // リッスンするポート
  hostname: "0.0.0.0", // バインドするネットワークインターフェース (0.0.0.0 はすべて)

  // fetch: サーバーの心臓部 - 着信リクエストを処理します
  async fetch(req: Request, server: Server): Promise<Response> {
    // req は標準の Web API Request オブジェクトです
    // server は Server インスタンス自体への参照です

    const url = new URL(req.url);

    // 基本的なルーティング例
    if (url.pathname === "/") {
      return new Response("Homepage");
    }
    if (url.pathname === "/about") {
      return new Response("About Us page");
    }
    if (url.pathname === "/greet" && req.method === "GET") {
        const name = url.searchParams.get("name") || "World";
        return new Response(`Hello, ${name}!`);
    }
     if (url.pathname === "/data" && req.method === "POST") {
        try {
            const data = await req.json(); // リクエストボディをJSONとして読み込みます
            console.log("Received data:", data);
            return new Response(JSON.stringify({ received: data }), {
               headers: { 'Content-Type': 'application/json' }
            });
        } catch (e) {
            return new Response("Invalid JSON body", { status: 400 });
        }
    }

    // デフォルトの 404 Not Found
    return new Response("Page Not Found", { status: 404 });
  },

  // error: fetch ハンドラ *外* で発生するエラーのオプションハンドラ
  error(error: Error): Response | Promise<Response> {
    console.error("[Server Error]", error);
    return new Response("Something went wrong!", { status: 500 });
  },

  // development: 開発時に役立つエラーページを表示するには true に設定 (デフォルト: !process.env.NODE_ENV=production)
   development: true,

   // 'websocket', 'tls' のような他のオプションは高度なユースケースに存在します
});

console.log(`Bun server listening on http://${server.hostname}:${server.port}`);

// サーバーオブジェクトとやり取りできます:
// server.stop() // サーバーを停止します
// server.reload({...}) // サーバー設定 (例: fetch ハンドラ) を動的に更新します

主な機能:

Bun.serve は、BunでウェブアプリケーションやAPIを構築するための強力かつシンプルな基盤を提供し、速度とウェブ標準への準拠を優先しています。

Bun Fetchクライアント

サーバーAPIを補完するものとして、BunはアウトバウンドHTTP(S)リクエストを行うためのグローバルな fetch 関数を提供します。この実装はWHATWG Fetch標準に厳密に準拠しており、ウェブ開発者にとって使い慣れたものにし、Bun.serve 内で使用される fetch 関数との一貫性を保証します。Bunのネイティブ実装は、クライアントサイドのネットワーキングタスクで高いパフォーマンスを保証します。

リクエストの作成:

基本的な使用法は、URLとオプションで設定オブジェクトを指定して fetch を呼び出すことです。

async function makeRequests() {
  const url = "https://httpbin.org"; // HTTPリクエストのテストに便利なサービス

  // --- 基本的なGETリクエスト ---
  console.log("--- GET Request ---");
  try {
    const getResponse = await fetch(`${url}/get?param1=value1`);

    console.log(`Status: ${getResponse.status} ${getResponse.statusText}`);

    // リクエストが成功したか確認 (ステータス 200-299)
    if (!getResponse.ok) {
      throw new Error(`HTTP error! status: ${getResponse.status}`);
    }

    // ヘッダーにアクセス
    console.log("Content-Type Header:", getResponse.headers.get('content-type'));

    // レスポンスボディをJSONとして読み込みます
    const getData = await getResponse.json();
    console.log("Response JSON:", getData.args); // httpbin.org/get はクエリパラメータを 'args' で返します

  } catch (error) {
    console.error("GET request failed:", error);
  }

  // --- JSONボディ付きPOSTリクエスト ---
  console.log("\n--- POST Request (JSON) ---");
  try {
     const postData = { name: "Bun", type: "Runtime" };
     const postResponse = await fetch(`${url}/post`, {
        method: "POST",
        headers: {
          // JSONを送信することを示す
          "Content-Type": "application/json",
          "Accept": "application/json", // JSONでの応答を希望することを示す
          "X-Custom-Header": "BunFetchExample",
        },
        // JSONの場合はボディを文字列化する必要がある
        body: JSON.stringify(postData),
     });

     if (!postResponse.ok) {
        throw new Error(`HTTP error! status: ${postResponse.status}`);
     }

     const postResult = await postResponse.json();
     console.log("POST Response JSON:", postResult.json); // httpbin.org/post は投稿されたJSONを 'json' で返します

  } catch (error) {
     console.error("POST request failed:", error);
  }

   // --- タイムアウト付きリクエスト ---
   console.log("\n--- GET Request with Timeout ---");
   try {
      const controller = new AbortController();
      const timeoutId = setTimeout(() => controller.abort(), 2000); // 2秒後に中断

      const timeoutResponse = await fetch(`${url}/delay/5`, { // このエンドポイントは5秒待機します
         signal: controller.signal // AbortSignal を渡す
      });

      clearTimeout(timeoutId); // fetch が早く完了した場合、タイムアウトをクリア
      console.log("Timeout request succeeded (unexpected for /delay/5)");

   } catch (error: any) {
      // シグナルが中断されたときに AbortError がスローされます
      if (error.name === 'AbortError') {
         console.log("Fetch aborted due to timeout, as expected.");
      } else {
         console.error("Timeout request failed:", error);
      }
   }
}

await makeRequests();

主な機能とオプション:

標準API: 使い慣れた fetch(url, options) シグネチャを使用します。

メソッド: すべての標準HTTPメソッド（GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS）をサポートします。method オプションで指定します。

ヘッダー: ヘッダーは headers オプションを使用して設定します。これは Headers オブジェクトまたはシンプルなキーと値のプレーンオブジェクトにできます。

リクエストボディ: body オプションは様々なタイプを受け入れます。

ApidogでAPIデザイン中心のアプローチを取る

APIの開発と利用をよりシンプルなことにする方法を発見できる

無料会員登録ダウンロード