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.