deno serve

deno serve runs a file as an HTTP server using Deno.serve(). The file must export a default object with a fetch handler. For a full guide on building HTTP servers, see Writing an HTTP Server.

Basic usage Jump to heading

server.ts

export default {
  fetch(_req: Request) {
    return new Response("Hello world!");
  },
} satisfies Deno.ServeDefaultExport;

›_

deno serve server.ts

By default, the server listens on port 8000. Override it with --port:

›_

deno serve --port=3000 server.ts

`deno serve` vs `deno run` Jump to heading

Both approaches start an HTTP server, and the difference is who calls Deno.serve():

With deno serve, Deno calls Deno.serve() for you. Your file just exports a default object with a fetch handler. Deno owns the listener, which lets it add features such as running multiple instances across threads with --parallel.
With deno run, you call Deno.serve() yourself inside the program. This gives you full control over the listen options and the surrounding code, and is the right choice when the server is one part of a larger program.

Use deno serve when the program is primarily an HTTP server and you want Deno to manage it; use deno run with Deno.serve() when you need to control how and when the server starts.

Default export shape Jump to heading

The file must export a default object that satisfies Deno.ServeDefaultExport. The object has two properties:

export interface ServeDefaultExport {
  fetch: ServeHandler;
  onListen?: (localAddr: Deno.Addr) => void;
}

`fetch` (required) Jump to heading

The fetch handler receives a standard Request and a ServeHandlerInfo object with connection metadata:

type ServeHandler = (
  request: Request,
  info: ServeHandlerInfo,
) => Response | Promise<Response>;

interface ServeHandlerInfo {
  remoteAddr: Deno.Addr; // remote address of the connection
  completed: Promise<void>; // resolves when the request completes
}

If the handler throws, the error is isolated to that request — the server continues serving.

`onListen` (optional) Jump to heading

Called once when the server starts listening. If omitted, a default message is logged to the console.

server.ts

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;

Any other properties on the default export are silently ignored. If fetch is missing, no server starts. If fetch or onListen exist but are not functions, a TypeError is thrown.

Routing requests Jump to heading

Use the request URL to route to different handlers:

server.ts

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;

Binding to a hostname Jump to heading

By default, deno serve listens on 0.0.0.0. Use --host to bind to a specific interface:

›_

deno serve --host=127.0.0.1 server.ts

Horizontal scaling Jump to heading

Run multiple server instances across CPU cores for better throughput:

›_

deno serve --parallel server.ts

Watch mode Jump to heading

Restart the server automatically when files change:

›_

deno serve --watch server.ts

Options Jump to heading

--allow-scripts

Allow running npm lifecycle scripts for the given packages Note: Scripts will only be executed when using a node_modules directory (--node-modules-dir).

--cached-only

Require that remote dependencies are already cached.

--cert

Load certificate authority from PEM encoded file.

--check

Enable type-checking. This subcommand does not type-check by default; pass --check=all to also type-check remote modules. Alternatively, use the 'deno check' subcommand.

--conditions

Use this argument to specify custom conditions for npm package exports. You can also use DENO_CONDITIONS env var. .

--config, -c

Configure different aspects of deno including TypeScript, linting, and code formatting. Typically the configuration file will be called deno.json or deno.jsonc and automatically detected; in that case this flag is not necessary.

--env-file

Load environment variables from local file Only the first environment variable with a given key is used. Existing process environment variables are not overwritten, so if variables with the same names already exist in the environment, their values will be preserved. Where multiple declarations for the same environment variable exist in your .env file, the first one encountered is applied. This is determined by the order of the files you pass as arguments.

--ext

Set content type of the supplied file.

--frozen-lockfile

Error out if lockfile is out of date.

--host

The TCP address to serve on, defaulting to 0.0.0.0 (all interfaces).

--import-map

Load import map file from local file or remote URL.

--inspect

Activate inspector on host:port [default: 127.0.0.1:9229]. Host and port are optional. Using port 0 will assign a random free port.

--inspect-brk

Activate inspector on host:port, wait for debugger to connect and break at the start of user script.

--inspect-publish-uid

--inspect-wait

Activate inspector on host:port and wait for debugger to connect before running user code.

--location

Value of globalThis.location used by some web APIs.

--lock

Check the specified lock file. (If value is not provided, defaults to "./deno.lock").

--min-dep-age

(Unstable) The age in minutes, ISO-8601 duration or RFC3339 absolute timestamp (e.g. '120' for two hours, 'P2D' for two days, '2025-09-16' for cutoff date, '2025-09-16T12:00:00+00:00' for cutoff time, '0' to disable).

--no-check

Skip type-checking. If the value of "remote" is supplied, diagnostic errors from remote modules will be ignored.

--no-clear-screen

Do not clear terminal screen when under watch mode.

--no-code-cache

Disable V8 code cache feature.

--no-config

Disable automatic loading of the configuration file.

--no-lock

Disable auto discovery of the lock file.

--no-npm

Do not resolve npm modules.

--no-remote

Do not resolve remote modules.

--node-modules-dir

Selects the node_modules directory mode for npm packages (not a path). One of: auto (create a local node_modules directory and install npm packages into it), manual (use the existing local node_modules directory, do not modify it), none (do not use a local node_modules directory; resolve npm packages from the global cache). Defaults to auto when the flag is passed without a value.

--node-modules-linker

Sets the linker mode for npm packages (isolated or hoisted).

--open

Open the browser on the address that the server is running on.

--parallel

Run multiple server workers in parallel. Parallelism defaults to the number of available CPUs or the value of the DENO_JOBS environment variable.

--port

The TCP port to serve on. Pass 0 to pick a random free port [default: 8000]

--preload

A list of files that will be executed before the main module.

--reload, -r

Reload source code cache (recompile TypeScript). With no value, reloads everything. Pass a comma-separated list of specifiers to reload only those modules; npm: reloads all npm modules; npm:chalk reloads a single npm module; jsr:@std/http/file-server,jsr:@std/assert/assert-equals reloads specific modules.

--require

A list of CommonJS modules that will be executed before the main module.

--seed

Set the random number generator seed.

--unsafely-ignore-certificate-errors

DANGER: Disables verification of TLS certificates.

--v8-flags

To see a list of all available flags use --v8-flags=--help Flags can also be set via the DENO_V8_FLAGS environment variable. Any flags set with this flag are appended after the DENO_V8_FLAGS environment variable.

--vendor

Toggles local vendor folder usage for remote modules and a node_modules folder for npm packages.

--watch

Watch for file changes and restart process automatically. Local files from entry point module graph are watched by default. Additional paths might be watched by passing them as arguments to this flag.

--watch-exclude

Exclude provided files/patterns from watch mode.

--watch-hmr

Watch for file changes and hot-replace modules. The process restarts if hot replacement fails. Local files from entry point module graph are watched by default. Additional paths might be watched by passing them as arguments to this flag.

deno serve

Basic usage Jump to heading

`deno serve` vs `deno run` Jump to heading

Default export shape Jump to heading

`fetch` (required) Jump to heading

`onListen` (optional) Jump to heading

Routing requests Jump to heading

Binding to a hostname Jump to heading

Horizontal scaling Jump to heading

Watch mode Jump to heading

Permissions Jump to heading

Options Jump to heading

Did you find what you needed?

This page

deno serve

Basic usage Jump to heading#

deno serve vs deno run Jump to heading#

Default export shape Jump to heading#

fetch (required) Jump to heading#

onListen (optional) Jump to heading#

Routing requests Jump to heading#

Binding to a hostname Jump to heading#

Horizontal scaling Jump to heading#

Watch mode Jump to heading#

Permissions Jump to heading#

Options Jump to heading#

Did you find what you needed?

This page

Basic usage Jump to heading

`deno serve` vs `deno run` Jump to heading

Default export shape Jump to heading

`fetch` (required) Jump to heading

`onListen` (optional) Jump to heading

Routing requests Jump to heading

Binding to a hostname Jump to heading

Horizontal scaling Jump to heading

Watch mode Jump to heading

Permissions Jump to heading

Options Jump to heading