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): RuntimeServerParameters: 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()