ArctonArcton
Introduction

What is Arcton?

A TypeScript backend framework built around typed context, an explicit middleware pipeline, and a route tree that modules merge into.

Arcton is a framework for building HTTP APIs in TypeScript. An application is an Arcton() instance: you register routes on it, compose behavior around them, and start it with listen().

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/health', () => ({ status: 'ok' }))

app.listen({ port: 3000 })

That is a complete, runnable file. bun src/index.ts serves it.

Handlers return values

A handler returns whatever the response should contain. Arcton maps the returned value to an HTTP response: an object becomes JSON, a string becomes text/plain, a Uint8Array becomes a binary body.

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/json', () => ({ ok: true }))
app.get('/text', () => 'plain text')
app.get('/empty', () => {})

app.listen()

When you need full control, return a Response and Arcton passes it through untouched. The complete mapping is in Response.

The route literal types the context

Arcton reads the path you wrote and types ctx.params from it:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/users/:userId/posts/:postId', ctx => {
  // ctx.params is { userId: string; postId: string }
  return { user: ctx.params.userId, post: ctx.params.postId }
})

app.listen()

Misspelling ctx.params.userID is a compile error, not a runtime undefined.

Context grows as you compose

provide() attaches values to the context and widens its type for everything registered afterwards:

import { Arcton } from '@arcton/core'

const app = Arcton()

app
  .provide(ctx => ({
    requestId: ctx.request.headers.get('x-request-id') ?? crypto.randomUUID()
  }))
  .get('/whoami', ctx => ({ requestId: ctx.requestId }))

app.listen()

ctx.requestId is typed on the handler because the provider was registered before the route. See Providers.

Applications are built from modules

A module is an Arcton() instance with its own prefix. Mounting one merges its routes into the parent's route tree:

import { Arcton } from '@arcton/core'

const users = Arcton({ prefix: '/users' })

users.get('/', () => [{ id: '1' }])
users.get('/:id', ctx => ({ id: ctx.params.id }))

const app = Arcton({ prefix: '/api' })

app.use(users)

app.listen()

This serves GET /api/users and GET /api/users/:id. See Modules.

Runtimes

The core has no dependency on any specific runtime. Bun and Node.js are both supported through adapters, selected at listen():

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

const app = Arcton()

app.get('/', () => 'Hello from Node.js')

app.listen({ adapter: nodeAdapter })

See Runtime support.

What Arcton includes

  • A route tree with static, dynamic and wildcard segments and defined precedence.
  • Middleware that is global, path-scoped or attached to a single route.
  • Per-route validation of params, query and body through Standard Schema, so Zod, Valibot and ArkType all work.
  • Body parsing by Content-Type, extensible with your own parsers.
  • WebSocket routes.
  • CORS as a separate package.
  • Bun and Node.js adapters, and the RuntimeAdapter interface behind them.

On this page