Bun.serveで、小さなWebサーバーを立てる方法

​​Bun​HTTP,TypeScript

Bun の Bun.serve を使うと、Express などのパッケージを入れなくても、TypeScript の1ファイルで HTTP サーバーを立てられます。パスごとの処理は routes にまとめ、URL の一部(:id など)やメソッド(GET、POST)ごとの振り分けも、そこに書けます。

動作確認用の小さな API サーバーや、フロントエンドの開発で使うモックサーバーを手早く用意したいときに向いています。この記事では、メモを読み書きする API を例に、書き方と、実際に返ってきた応答をそのまま載せます。

補足

検証環境は Ubuntu 24.04(x86_64)、Bun 1.4.4 です。リクエストは curl 8.5.0 で送りました。HTTPS(tls)、WebSocket、HTTP/2・HTTP/3、HTML の import、Windows と macOS は試していません。公式ドキュメントは、検証に使った版(タグ bun-v1.4.4)の元ファイルを GitHub で確認し、リンクもそこに張っています。

メモの API を1ファイルで書く

次の server.ts が、今回のサーバーのすべてです。メモはメモリ上の配列に持たせているので、サーバーを止めると消えます。

ts
type Memo = { id: number; text: string };
const memos: Memo[] = [{ id: 1, text: "牛乳を買う" }];

const server = Bun.serve({
  routes: {
    // 決まった内容を返すだけなら、Response をそのまま置ける
    "/health": new Response("OK"),

    // :id の部分は req.params.id で受け取る
    "/hello/:name": (req) => new Response(`こんにちは、${req.params.name}さん\n`),

    // メソッドごとに処理を分ける
    "/api/memos": {
      GET: () => Response.json(memos),
      POST: async (req) => {
        const body = (await req.json()) as { text?: string };
        if (!body.text) {
          return Response.json({ error: "text は必須です" }, { status: 400 });
        }
        const memo = { id: memos.length + 1, text: body.text };
        memos.push(memo);
        return Response.json(memo, { status: 201 });
      },
    },

    "/api/memos/:id": (req) => {
      const memo = memos.find((m) => m.id === Number(req.params.id));
      if (!memo) return Response.json({ error: "見つかりません" }, { status: 404 });
      return Response.json(memo);
    },
  },

  // どのルートにも当たらなかったリクエスト
  fetch() {
    return new Response("Not Found\n", { status: 404 });
  },
});

console.log(`listening on ${server.url}`);

routes の値によく使うのは、次の3つの形です。Response そのもの、Request を受け取って Response を返す関数、そして GET や POST をキーにした関数のまとまりです(公式ドキュメントの Server のページ)。返す値は Web 標準の Response なので、JSON は Response.json() で作れます。なお、routes は Bun 1.2.3 から使えるオプションで、それより前の版では fetch が必須です。

bun server.ts で起動すると、次の1行が出ました。ポートを指定しなければ 3000 番で待ち受けます。

text
listening on http://localhost:3000/

curl で読み書きする

まずは Response をそのまま置いた /health です。ヘッダーを見ると、etag が自動で付いていました。

text
$ curl -i http://localhost:3000/health
HTTP/1.1 200 OK
Content-Type: text/plain;charset=utf-8
etag: "5afa14a82295204f"
Date: Sat, 14 Nov 2026 08:13:30 GMT
Content-Length: 2

OK

Response をそのまま置いたルートは、サーバーを起動したときの内容がずっと返ります。中身を変えるには server.reload() を呼びます(公式ドキュメントのルーティングのページ)。

/hello/:name では、URL の :name の部分が req.params.name に入ります。日本語をパーセントエンコードして送っても、デコードされた文字列で受け取れました。

text
$ curl http://localhost:3000/hello/neko
こんにちは、nekoさん

$ curl http://localhost:3000/hello/%E3%81%AD%E3%81%93
こんにちは、ねこさん

/api/memos に GET と POST を送った結果です。Response.json() で返すと、Content-Type は application/json;charset=utf-8 になりました。

text
$ curl -i http://localhost:3000/api/memos
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Date: Sat, 14 Nov 2026 08:13:30 GMT
Content-Length: 35

[{"id":1,"text":"牛乳を買う"}]
$ curl -i -X POST -H "Content-Type: application/json" -d '{"text":"猫の爪を切る"}' http://localhost:3000/api/memos
HTTP/1.1 201 Created
Content-Type: application/json;charset=utf-8
Date: Sat, 14 Nov 2026 08:13:30 GMT
Content-Length: 36

{"id":2,"text":"猫の爪を切る"}

text のない JSON を POST すると、コードで決めたとおり 400 が返りました。追加したメモは、一覧でも ID 指定でも取り出せます。

text
$ curl -i -X POST -H "Content-Type: application/json" -d '{}' http://localhost:3000/api/memos
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=utf-8
Date: Sat, 14 Nov 2026 08:13:30 GMT
Content-Length: 32

{"error":"text は必須です"}
$ curl http://localhost:3000/api/memos
[{"id":1,"text":"牛乳を買う"},{"id":2,"text":"猫の爪を切る"}]
$ curl http://localhost:3000/api/memos/2
{"id":2,"text":"猫の爪を切る"}

書いていないメソッドは、fetch に回る

/api/memos には GET と POST しか書いていません。ここへ DELETE を送ると、405(Method Not Allowed)ではなく、fetch に書いた 404 が返りました。どのパスにも当たらない /nothing と同じ応答です。

text
$ curl -i -X DELETE http://localhost:3000/api/memos
HTTP/1.1 404 Not Found
content-type: text/plain;charset=utf-8
Date: Sat, 14 Nov 2026 08:13:30 GMT
Content-Length: 10

Not Found

fetch を書かずに routes だけにしたサーバー(GET だけを持つ /api/memos)でも試しました。この場合は、DELETE も /nothing も、本文が空の 404 になりました。

text
$ curl -i -X DELETE http://localhost:3000/api/memos
HTTP/1.1 404 Not Found
Date: Sat, 14 Nov 2026 08:13:31 GMT
Content-Length: 0

API の利用者に「このメソッドは使えない」と伝えたいときは、DELETE のキーを足して 405 を返すなど、自分で書く必要があります。

ルートは、書いた順ではなく具体的なものが優先される

ルートの書き方には、決まったパス、:id のようなパラメーター付き、* を使ったワイルドカードがあります。公式ドキュメントによると、当てはめる順番は「決まったパス、パラメーター付き、ワイルドカード、/*」です(ルーティングのページにある、ルートの優先順位の説明)。

これを確かめるため、わざと広いものから順に書いた order.ts を用意しました。

ts
const server = Bun.serve({
  routes: {
    "/*": () => new Response("/* に当たった\n"),
    "/api/*": () => new Response("/api/* に当たった\n"),
    "/api/users/:id": (req) => new Response(`/api/users/:id に当たった(id=${req.params.id})\n`),
    "/api/users/me": () => new Response("/api/users/me に当たった\n"),
  },
});
console.log(`listening on ${server.url}`);

それぞれのパスに送ると、次のようになりました。

リクエストしたパス 当たったルート
/api/users/me /api/users/me
/api/users/42 /api/users/:id(id=42)
/api/users/42/posts /api/*
/api/other /api/*
/top /*

一番上に書いた /* が、ほかのルートを横取りすることはありませんでした。/api/users/42/posts のように :id の後ろにまだ続くパスは、/api/users/:id には当たらず、/api/* に回っています。

例外が起きると、既定ではソースコード入りの画面が返る

ハンドラーの中で例外が起きたときの応答は、設定によって大きく変わります。次の boom.ts で確かめました。

ts
const server = Bun.serve({
  routes: {
    "/boom": () => {
      throw new Error("ここで失敗しました");
    },
  },
});
console.log(`listening on ${server.url} development=${server.development}`);

何も設定せずに起動すると、development=true と表示されました。Bun.serve は、既定で開発モードで動きます(公式ドキュメントのエラー処理のページ)。このとき /boom へのリクエストには、ステータス 500 で、50,298 バイトの HTML が返りました。ブラウザーで開くと、次の画面になります。

Bun の開発モードのエラー画面。エラーの文言「ここで失敗しました」、ファイル名と行番号 /boom.ts:4:17、throw している行を含むソースコード4行が表示されている
開発モードで例外が起きたときに、ブラウザーに返る画面

エラーの文言だけでなく、ファイル名と行番号、例外を投げた行までのソースコードが、リクエストした人の画面に出ています。応答の HTML の中には、サーバーの作業フォルダのパスも入っていました。

注意

開発モードのまま公開しないでください。公開する環境では NODE_ENV=production を付けて起動するか、development: false を指定してください。公式ドキュメントによると、bun run に --production を付けても、この画面は止まりません(このフラグは bun build や bun install のもので、bun run は無視します)。

NODE_ENV=production を付けて同じファイルを起動すると、development=false になり、応答は短い文字列だけになりました。

text
$ curl -i http://localhost:3000/boom
HTTP/1.1 500 Internal Server Error
content-type: text/plain
Date: Sat, 14 Nov 2026 08:13:34 GMT
Content-Length: 21

Something went wrong!

応答の中身を自分で決めたいときは、error ハンドラーを書きます。公式ドキュメントにある error ハンドラーの説明によると、error が返した Response は、開発モードのエラー画面の代わりに返ります。

ts
const server = Bun.serve({
  routes: {
    "/boom": () => {
      throw new Error("ここで失敗しました");
    },
  },
  error(error) {
    console.error(`error handler: ${error.message}`);
    return Response.json({ error: "サーバーの中でエラーが起きました" }, { status: 500 });
  },
});
console.log(`listening on ${server.url} development=${server.development}`);

開発モードのまま(development=true)でも、返ってきたのはこの JSON だけでした。サーバー側のログには error handler: ここで失敗しました が出ています。

text
$ curl -i http://localhost:3000/boom
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=utf-8
Date: Sat, 14 Nov 2026 08:13:35 GMT
Content-Length: 60

{"error":"サーバーの中でエラーが起きました"}

最初の server.ts で、壊れた JSON({broken)を POST したときも、req.json() が SyntaxError を投げ、ステータス 500 で開発モードのエラー画面の HTML(49,995 バイト)が返りました。リクエストの本文を読む処理は、try で囲むか、error ハンドラーで受けておくと安心です。

ポートの決め方と、server.url の扱い

default-port.ts は、port を書かずに起動してポート番号を表示するだけのファイルです。そのまま起動すると 3000 番、環境変数 PORT を付けるとその番号になりました。公式ドキュメントによると、BUN_PORT、PORT、NODE_PORT の環境変数や、bun --port=4002 のような指定も使えます(Server のページの、ポートの設定について書かれた節)。

text
$ bun default-port.ts
port=3000
$ PORT=8080 bun default-port.ts
port=8080

port: 0 を指定すると、空いているポートが選ばれます。テストでサーバーを立てるときなど、番号がぶつからないようにしたい場面で使えます。2回起動すると、2回とも違う番号になりました。

次のコードは、選ばれた番号と URL を表示し、server.url にパスをつなぐ2つの書き方を比べたものです。APP_PORT は、このファイルのために用意した環境変数です。

ts
const server = Bun.serve({
  port: Number(process.env.APP_PORT ?? 3000),
  fetch: () => new Response("hi\n"),
});
console.log(`port=${server.port} url=${server.url}`);
console.log(`文字列でつなぐ: ${server.url}/users`);
console.log(`new URL で作る: ${new URL("/users", server.url)}`);
server.stop();
text
$ APP_PORT=0 bun port.ts
port=43339 url=http://localhost:43339/
文字列でつなぐ: http://localhost:43339//users
new URL で作る: http://localhost:43339/users
$ APP_PORT=0 bun port.ts
port=34541 url=http://localhost:34541/
文字列でつなぐ: http://localhost:34541//users
new URL で作る: http://localhost:34541/users

server.url は末尾が / の URL なので、テンプレート文字列でつなぐとスラッシュが2つ並びます。パスを足すときは new URL("/users", server.url) のように書きます。

すでにほかのプロセスが 3000 番を使っているときは、起動の時点で EADDRINUSE のエラーになり、終了コード 1 で止まりました(パスは /path/to/app に置き換えています)。

text
1 | const server = Bun.serve({
                       ^
error: Failed to start server. Is port 3000 in use?
 syscall: "listen",
   errno: 0,
    code: "EADDRINUSE"

      at /path/to/app/port.ts:1:20

Bun v1.4.4 (Linux x64)

前に起動したサーバーが残っていないかを確かめるか、PORT で別の番号を指定して起動し直します。

​Posted by 86