deno serve basic usage
deno serve runs a file as an HTTP server using Deno.serve(). The file must export a default object with a fetch handler. By default, the server listens on port 8000.
Deno · Reference · all subjects
cli commands/serve
22 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
deno serve default port
deno serve listens on port 8000 by default. Override it with the --port flag.
deno serve --port flag
Use deno serve --port=PORT to set a custom port for the HTTP server. Example: deno serve --port=3000 server.ts
deno serve vs deno run
With deno serve, Deno calls Deno.serve() for you and owns the listener, enabling features like --parallel for running multiple instances across threads. With deno run, you call Deno.serve() yourself, giving full control over listen options. Use deno serve when the program is primarily an HTTP server; use deno run when you need to control how and when the server starts.
ServeDefaultExport interface
The file exported default must satisfy Deno.ServeDefaultExport with two properties: fetch (required, type ServeHandler) and onListen (optional, type (localAddr: Deno.Addr) => void).
ServeHandler type and ServeHandlerInfo
The fetch handler has type ServeHandler = (request: Request, info: ServeHandlerInfo) => Response | Promise<Response>. ServeHandlerInfo has two properties: remoteAddr (Deno.Addr, remote address of the connection) and completed (Promise<void>, resolves when the request completes).
deno serve fetch handler error handling
If the fetch handler throws an error, the error is isolated to that request and the server continues serving.
deno serve onListen callback
The onListen callback is called once when the server starts listening. If omitted, a default message is logged to the console.
deno serve default export validation
Any properties on the default export other than fetch and onListen are silently ignored. If fetch is missing, no server starts. If fetch or onListen exist but are not functions, a TypeError is thrown.
deno serve --host flag
By default, deno serve listens on 0.0.0.0. Use --host to bind to a specific interface. Example: deno serve --host=127.0.0.1 server.ts
deno serve --parallel flag
Use deno serve --parallel to run multiple server instances across CPU cores for better throughput.
deno serve --watch flag
Use deno serve --watch to restart the server automatically when files change.
deno serve permissions
deno serve automatically allows the server to listen without requiring --allow-net. Additional permissions like file reads must be granted explicitly. Example: deno serve --allow-read server.ts
deno serve basic example
export default { fetch(_req: Request) { return new Response("Hello world!"); }, } satisfies Deno.ServeDefaultExport; Then run: deno serve server.ts This example shows a minimal HTTP server that returns a hello world response.
deno serve fetch with metadata example
export default { fetch(request, info) { const { hostname, port } = info.remoteAddr as Deno.NetAddr; console.log(`${request.method} ${request.url} from ${hostname}:${port}`); return new Response("Hello, World!", { headers: { "content-type": "text/plain" }, }); }, onListen({ hostname, port }) { console.log(`Server running at http://${hostname}:${port}/`); }, } satisfies Deno.ServeDefaultExport; This example shows how to access connection metadata and use the onListen callback.
deno serve routing example
export default { fetch(request: Request) { const url = new URL(request.url); if (url.pathname === "/api/health") { return Response.json({ status: "ok" }); } return new Response("Not found", { status: 404 }); }, } satisfies Deno.ServeDefaultExport; This example shows how to use the request URL to route to different handlers.
Deno.serve legacy abort behavior default
Historically, Deno.serve fired the abort event on a request's AbortSignal (request.signal) whenever the request finished, including when the handler returned a successful response. This legacy abort behavior is enabled by default today.
--unstable-no-legacy-abort flag
The --unstable-no-legacy-abort flag opts in to the corrected abort behavior in Deno.serve, which will become the default in an upcoming release. This flag can be passed as a CLI argument or enabled in deno.json under the unstable array.
New abort behavior with --unstable-no-legacy-abort
With --unstable-no-legacy-abort enabled, request.signal aborts only when the client actually cancels the request or the connection is lost before the response has been fully sent. A successful response no longer triggers an abort.
ServeHandlerInfo.completed promise
The completed promise on the second argument to the Deno.serve handler (ServeHandlerInfo) is the intended way to observe delivery. It resolves once the response, including any streaming body, has been sent to the client, and rejects if delivery failed before completing. The promise is lazily created, so handlers that never read info.completed pay no extra cost.
Migration to new abort behavior example
Example of using ServeHandlerInfo.completed: Deno.serve((req, info) => { info.completed.then(() => { console.log("response fully delivered"); }).catch((err) => { console.error("response was not sent successfully:", err); }); return new Response(someStream); });
Migration steps for new abort behavior
To migrate to the new abort behavior: (1) Enable the flag while testing by running 'deno run --unstable-no-legacy-abort main.ts' or by adding 'unstable: ["no-legacy-abort"]' to deno.json, and (2) Use request.signal only for cancellation, and move completion/cleanup logic onto info.completed or the handler's return path.