ende serve

ende serve runs a file as an HTTP server using Ende.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

server.ts
export default {
  fetch(_req: Request) {
    return new Response("Hello world!");
  }
} satisfies Ende.ServeDefaultExport;
ende serve server.ts

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

ende serve --port=3000 server.ts

ende serve vs ende run

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

  • With ende serve, Ende calls Ende.serve() for you. Your file just exports a default object with a fetch handler. Ende owns the listener, which lets it add features such as running multiple instances across threads with --parallel.
  • With ende run, you call Ende.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 ende serve when the program is primarily an HTTP server and you want Ende to manage it; use ende run with Ende.serve() when you need to control how and when the server starts.

Default export shape

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

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

fetch (required)

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: Ende.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)

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 Ende.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 Ende.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

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 Ende.ServeDefaultExport;

Binding to a hostname

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

ende serve --host=127.0.0.1 server.ts

Horizontal scaling

Run multiple server instances across CPU cores for better throughput:

ende serve --parallel server.ts

Watch mode

Restart the server automatically when files change:

ende serve --watch server.ts

Permissions

ende serve automatically allows the server to listen without requiring --allow-net. Additional permissions (like file reads) must be granted explicitly:

ende serve --allow-read server.ts

Command line usage:

serve

Run a server

Options

--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 'ende check' subcommand.

--config, -c

Configure different aspects of ende including TypeScript, linting, and code formatting. Typically the configuration file will be called ende.json or ende.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 "./ende.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-remote

Do not resolve remote modules.

--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 ENDE_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; jsr:@ende/http/file-server,jsr:@ende/assert/equals reloads specific modules.

--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 ENDE_V8_FLAGS environment variable. Any flags set with this flag are appended after the ENDE_V8_FLAGS environment variable.

--vendor

Toggles local vendor folder usage for remote modules.

--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.