Routing - BunDocumentation Index
Fetch the complete documentation index at: /docs/llms.txt
Use this file to discover all available pages before exploring further.
Skip to main contentBun home pageDefine routes in Bun.serve using static paths, parameters, and wildcards
Bun.serve({
routes: {
"/": () => new Response("Home"),
"/api": () => Response.json({ success: true }),
"/users": async () => Response.json({ users: [] }),
},
fetch() {
return new Response("Unmatched route");
},
});
Routes in Bun.serve() receive a BunRequest (which extends Request) and return a Response or Promise. This makes it easier to use the same code for both sending & receiving HTTP requests.
// Simplified for brevity
interface BunRequestT extends string> extends Request {
params: RecordT, string>;
readonly cookies: CookieMap;
}
Asynchronous Routes
Async/await
You can use async/await in route handlers to return a Promise.
import { sql, serve } from "bun";
serve({
port: 3001,
routes: {
"/api/version": async () => {
const [version] = await sql`SELECT version()`;
return Response.json(version);
},
},
});
Promise
You can also return a Promise from a route handler.
import { sql, serve } from "bun";
serve({
routes: {
"/api/version": () => {
return new Promise(resolve => {
setTimeout(async () => {
const [version] = await sql`SELECT version()`;
resolve(Response.json(version));
}, 100);
});
},
},
});
Route precedence
Routes are matched in order of specificity:
Exact routes (/users/all)
Parameter routes (/users/:id)
Wildcard routes (/users/*)
Global catch-all (/*)
Bun.serve({
routes: {
// Most specific first
"/api/users/me": () => new Response("Current user"),
"/api/users/:id": req => new Response(`User ${req.params.id}`),
"/api/*": () => new Response("API catch-all"),
"/*": () => new Response("Global catch-all"),
},
});
Type-safe route parameters
TypeScript parses route parameters when passed as a string literal, so that your editor will show autocomplete when accessing request.params.
index.tsimport type { BunRequest } from "bun";
Bun.serve({
routes: {
// TypeScript knows the shape of params when passed as a string literal
"/orgs/:orgId/repos/:repoId": req => {
const { orgId, repoId } = req.params;
return Response.json({ orgId, repoId });
},
"/orgs/:orgId/repos/:repoId/settings": (
// optional: you can explicitly pass a type to BunRequest:
req: BunRequest"/orgs/:orgId/repos/:repoId/settings">,
) => {
const { orgId, repoId } = req.params;
return Response.json({ orgId, repoId });
},
},
});
Percent-encoded route parameter values are automatically decoded. Unicode characters are supported. Invalid unicode is replaced with the unicode replacement character &0xFFFD;.
Static responses
Routes can also be Response objects (without the handler function). Bun.serve() optimizes it for zero-allocation dispatch - perfect for health checks, redirects, and fixed content:
Bun.serve({
routes: {
// Health checks
"/health": new Response("OK"),
"/ready": new Response("Ready", {
headers: {
// Pass custom headers
"X-Ready": "1",
},
}),
// Redirects
"/blog": Response.redirect("https://bun.com/blog"),
// API responses
"/api/config": Response.json({
version: "1.0.0",
env: "production",
}),
},
});
Static responses do not allocate additional memory after initialization. You can generally expect at least a 15% performance improvement over manually returning a Response object.
Static route responses are cached for the lifetime of the server object. To reload static routes, call server.reload(options).
File Responses vs Static Responses
When serving files in routes, there are two distinct behaviors depending on whether you buffer the file content or serve it directly:
Bun.serve({
routes: {
// Static route - content is buffered in memory at startup
"/logo.png": new Response(await Bun.file("./logo.png").bytes()),
// File route - content is read from filesystem on each request
"/download.zip": new Response(Bun.file("./download.zip")),
},
});
Static routes (new Response(await file.bytes())) buffer content in memory at startup:
Zero filesystem I/O during requests - content served entirely from memory
ETag support - Automatically generates and validates ETags for caching
If-None-Match - Returns 304 Not Modified when client ETag matches
No 404 handling - Missing files cause startup errors, not runtime 404s
Memory usage - Full file content stored in RAM
Best for: Small static assets, API responses, frequently accessed files
File routes (new Response(Bun.file(path))) read from filesystem per request:
Filesystem reads on each request - checks file existence and reads content
Built-in 404 handling - Returns 404 Not Found if file doesn’t exist or becomes inaccessible
Last-Modified support - Uses file modification time for If-Modified-Since headers
If-Modified-Since - Returns 304 Not Modified when file hasn’t changed since client’s cached version
Range request support - Automatically handles partial content requests with Content-Range headers
Streaming transfers - Uses buffered reader with backpressure handling for efficient memory usage
Memory efficient - Only buffers small chunks during transfer, not entire file
Best for: Large files, dynamic content, user uploads, files that change frequently
Streaming files
To stream a file, return a Response object with a BunFile object as the body.
Bun.serve({
fetch(req) {
return new Response(Bun.file("./hello.txt"));
},
});
Bun.serve({
fetch(req) {
// parse `Range` header
const [start = 0, end = Infinity] = req.headers
.get("Range") // Range: bytes=0-100
.split("=") // ["Range: bytes", "0-100"]
.at(-1) // "0-100"
.split("-") // ["0", "100"]
.map(Number); // [0, 100]
// return a slice of the file
const bigFile = Bun.file("./big-video.mp4");
return new Response(bigFile.slice(start, end));
},
});
fetch request handler
The fetch handler handles incoming requests that weren’t matched by any route. It receives a Request object and returns a Response or Promise.
Bun.serve({
fetch(req) {
const url = new URL(req.url);
if (url.pathname === "/") return new Response("Home page!");
if (url.pathname === "/blog") return new Response("Blog!");
return new Response("404!");
},
});
The fetch handler supports async/await:
import { sleep, serve } from "bun";
serve({
async fetch(req) {
const start = performance.now();
await sleep(10);
const end = performance.now();
return new Response(`Slept for ${end - start}ms`);
},
});
Promise-based responses are also supported:
Bun.serve({
fetch(req) {
// Forward the request to another server.
return fetch("https://example.com");
},
});
You can also access the Server object from the fetch handler. It’s the second argument passed to the fetch function.
// `server` is passed in as the second argument to `fetch`.
const server = Bun.serve({
fetch(req, server) {
const ip = server.requestIP(req);
return new Response(`Your IP is ${ip.address}`);
},
});
Was this page helpful?
Routing - Bun,AI智能索引,全网链接索引,智能导航,网页索引
- Define routes in Bun.serve using static paths, parameters, and wildcards