ArctonArcton
API Reference

listen()

Starts serving requests and returns a handle to the running server

listen() is the last call in an Arcton application:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/', () => 'Hello, Arcton!')

const server = app.listen({ port: 3000 })

console.log(`Listening on ${server.url}`)

See Listen options for the usage-first guide.

listen

Purpose: starts the server through the chosen adapter.

Signature

import type { ArctonListenOptions } from '@arcton/core'
import type { RuntimeServer } from '@arcton/contracts'

declare function listen(options?: ArctonListenOptions): RuntimeServer

Parameters: an optional ArctonListenOptions, documented below.

Return type: RuntimeServer.

Behavior: prints a startup banner — the Arcton figlet logo, the Arcton version, the runtime name and version, the env, and the listening URL — then returns a RuntimeServer. Routes, use(), and provide() calls made after listen() don't affect requests already flowing through routes registered before it, since each route's pipeline is snapshotted at registration time. Unless gracefulShutdown is false, it also registers the returned server with a process-wide shutdown coordinator so a SIGTERM/SIGINT drains it — see Graceful shutdown.

Errors: if any ws() route is registered and the chosen adapter's capabilities.websocket is false, listen() throws Runtime "<adapter.name>" does not support WebSocket routes.. Both shipped adapters — bunAdapter and nodeAdapter — support WebSockets, so this only matters with a custom adapter. It also throws if shutdownTimeout is provided but isn't a positive, finite number.

ArctonListenOptions

Purpose: the options object accepted by listen().

Signature

import type { RuntimeAdapter } from '@arcton/contracts'

interface ArctonListenOptions {
  port?: number
  hostname?: string
  adapter?: RuntimeAdapter
  env?: string
  maxBodySize?: number
  gracefulShutdown?: boolean
  shutdownTimeout?: number
}

Parameters

Prop

Type

Behavior: see Environment for what env does (and only does), Runtime types for the RuntimeAdapter interface, and Adapters for the bunAdapter/nodeAdapter values.

gracefulShutdown and shutdownTimeout control the process-wide SIGTERM/SIGINT handling described in Graceful shutdown. gracefulShutdown: false opts a given listen() call out entirely — useful when the host application manages process signals itself, since a graceful shutdown ends by calling process.exit(), terminating the whole process, not just this server.

RuntimeServer

Purpose: the handle listen() returns for the running server.

Signature

interface RuntimeServer {
  readonly port: number
  readonly url: URL
  stop(closeActiveConnections?: boolean): void | Promise<void>
}

Parameters

Prop

Type

Behavior: port and url reflect the address actually bound — useful when port: 0 picked a free one. stop() shuts the server down; it returns void on the Bun adapter and a Promise<void> on the Node adapter. This is the type used throughout Testing to start a server on port: 0, exercise it with real fetch calls, and tear it down afterward.

Example

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/', () => 'ok')

const server = app.listen({ port: 0 })

const res = await fetch(server.url)
console.log(res.status, server.port)

await server.stop()

On this page