ArctonArcton
Configuration

Listen Options

Configure the port, hostname, adapter and environment label passed to app.listen().

Starting a server

app.listen() takes an optional options object and returns a RuntimeServer:

import { Arcton } from '@arcton/core'

const app = Arcton()

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

app.listen({ port: 8080, hostname: '0.0.0.0' })

Every field is optional:

Prop

Type

Calling app.listen() with no arguments starts on port 3000 using the Bun adapter:

import { Arcton } from '@arcton/core'

const app = Arcton()

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

app.listen()

Picking a free port

Passing port: 0 asks the OS for a free port instead of a fixed one. Read the actual port back from the returned server:

import { Arcton } from '@arcton/core'

const app = Arcton()

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

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

console.log(server.port) // an OS-assigned port
console.log(server.url) // e.g. http://localhost:54231/

server.stop()

This is exactly the pattern used to test a real app end to end — see Testing overview.

Choosing an adapter

adapter selects which runtime serves the app. It defaults to bunAdapter. Pass nodeAdapter to run on Node.js instead:

import { nodeAdapter } from '@arcton/adapter-node'
import { Arcton } from '@arcton/core'

const app = Arcton()

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

app.listen({ adapter: nodeAdapter })

See Adapters for what an adapter is, and Runtime support for the concrete differences between the two shipped adapters.

The startup banner and the returned server

listen() prints a startup banner — the Arcton wordmark, followed by the Arcton version, the runtime name and version, the environment label, and the listening URL. The env option controls only that label; see Environment for the details.

It returns a RuntimeServer:

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

stop() returns void on the Bun adapter and a Promise<void> on the Node adapter, so awaiting it is always safe:

import { Arcton } from '@arcton/core'

const app = Arcton()

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

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

await server.stop()

See listen() for the full API reference.

Graceful shutdown

By default, listen() drains the server on SIGTERM/SIGINT instead of leaving termination to the runtime's default behavior: it stops accepting new connections, waits for in-flight requests to finish (up to shutdownTimeout, 10 seconds by default), then exits the process. If a request is still running once the timeout elapses, active connections are force-closed instead.

import { Arcton } from '@arcton/core'

const app = Arcton()

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

app.listen({ shutdownTimeout: 5000 })

gracefulShutdown is intended for applications where Arcton owns the process lifecycle — on signal, it calls process.exit(), which ends the whole process, not just this server. Set it to false when the host application manages process signals itself (e.g. Arcton embedded inside a larger process, or a runtime where OS signals aren't meaningful):

import { Arcton } from '@arcton/core'

const app = Arcton()

app.listen({ gracefulShutdown: false })

A second SIGTERM/SIGINT received while already shutting down is ignored — it doesn't start a second, concurrent drain.

On this page