Bun.serveで、小さなWebサーバーを立てる方法
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 が、今回のサーバーのすべてです。メモはメモリ上の配列に持たせているので、サーバーを止めると消えます。
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 番で待ち受けます。
listening on http://localhost:3000/
curl で読み書きする
まずは Response をそのまま置いた /health です。ヘッダーを見ると、etag が自動で付いていました。
$ 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 に入ります。日本語をパーセントエンコードして送っても、デコードされた文字列で受け取れました。
$ 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 になりました。
$ 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 指定でも取り出せます。
$ 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 と同じ応答です。
$ 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 になりました。
$ 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 を用意しました。
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 で確かめました。
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 が返りました。ブラウザーで開くと、次の画面になります。

エラーの文言だけでなく、ファイル名と行番号、例外を投げた行までのソースコードが、リクエストした人の画面に出ています。応答の HTML の中には、サーバーの作業フォルダのパスも入っていました。
開発モードのまま公開しないでください。公開する環境では NODE_ENV=production を付けて起動するか、development: false を指定してください。公式ドキュメントによると、bun run に --production を付けても、この画面は止まりません(このフラグは bun build や bun install のもので、bun run は無視します)。
NODE_ENV=production を付けて同じファイルを起動すると、development=false になり、応答は短い文字列だけになりました。
$ 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 は、開発モードのエラー画面の代わりに返ります。
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: ここで失敗しました が出ています。
$ 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 のページの、ポートの設定について書かれた節)。
$ bun default-port.ts
port=3000
$ PORT=8080 bun default-port.ts
port=8080
port: 0 を指定すると、空いているポートが選ばれます。テストでサーバーを立てるときなど、番号がぶつからないようにしたい場面で使えます。2回起動すると、2回とも違う番号になりました。
次のコードは、選ばれた番号と URL を表示し、server.url にパスをつなぐ2つの書き方を比べたものです。APP_PORT は、このファイルのために用意した環境変数です。
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();
$ 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 に置き換えています)。
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 で別の番号を指定して起動し直します。





