How it works
One language, two (or three) targets
You write .selm files. In selm.toml you set target to "erlang" (default), "javascript", or "atomvm".
javascript: browser SPAs, and Cloudflare Workers whenmainisFetch.HandlerorServer.Programerlang: HTTP servers, databases, websockets, and HTML rendered on the BEAMatomvm: small programs for microcontrollers
A full-stack project is usually Erlang for the server, plus an optional [client].entry that builds a JavaScript SPA beside it.
The Elm Architecture, still
Whether you are in the browser or on the server, programs follow the same shape:
Model: the data you keep in memoryMsg: events that happened (a click, a timer, a message from another process)update: turn aMsginto a newModeland maybe some commandsview/handle: turn theModelinto HTML, or turn aRequestinto aResponse
If you have used Elm, you already know this loop. selm keeps it on purpose.
Where state lives on the server
This is the idea that trips people up, and the one that makes selm servers scale.
- Each HTTP request runs in its own process and calls
handle. Routes that never talk to the program stay fully concurrent. - The program beside the listener (
Server.application) holds short-lived in-memory state: counters, mailboxes, open AI sessions, timers. - Durable data lives in the database, reached through
Repo.transactionand database modules.
Use Process.send when you do not need a reply. Use Process.call when you do (with a timeout). Keep update fast: slow work that changes the model is Task.attempt; work that touches no model is Task.spawn.
Optional BEAM distribution (--sname / --name plus an explicit --cookie, or SELM_NODE / SELM_COOKIE / [distribution] cookie) names the node so selm console can attach, Node / Erpc can reach peers, and Process.remoteSubject can address a registered name on another node. There is no default cookie.
Cloudflare Workers (JavaScript target)
On Workers the same OTP shape shows up with different hardware underneath.
| Idea | BEAM (`target = "erlang"`) | Workers (`target = "javascript"`) |
|---|---|---|
| HTTP gate | Server.application listener + request processes | Worker fetch gate from Server.application |
| Named process | Process / actor under a Supervisor | Server.durable singleton + Server.instance (idFromName(kind) / kind:id) |
| Gate TEA | In-memory program beside the listener | Isolate-local init / update / subscriptions; Server.send / snapshot |
| Call / cast | Process.call / Process.send (reply Subject) | Server.call / cast / askMap (reply Subject + Server.reply); gate→DO prefers selmMailbox (never proxy raw client requests to stub fetch) |
| Durable state | Database via Repo.transaction | Versioned model blob + Server.Storage / Server.Env; optional SQLite (new_sqlite_classes / Database.Sql) |
| Timers | Subscriptions / process timers | Server.scheduleIn / cancelAlarm + onAlarm (getAlarm / alarmInfo) |
| Placement / HTTP-in-DO | N/A | locationHint / jurisdiction; forward + withFetch |
| Channels | channel module + binary wire + Cowboy WS | Server.Socket.supervised + Server.Channel.define (explicit JSON; hibernatable DO WS) |
| Crash | OTP restart strategy | Server.Crash + nested strategies / withRestart (clears model envelope, not Storage/SQL) |
One emitted SelmObject class multiplexes every supervised child. Wire it in wrangler.toml (selm wrangler init / selm wrangler check). Walk examples/21_durable_counter and examples/22_durable_chat; Workers APIs are documented in runtime/server/*.selm (stdlib Server is the BEAM listener).
Layers of a selm server
A typical full-stack app stacks these pieces. You can start with only HTTP and grow into the rest.
| Layer | What it does |
|---|---|
| Schema / models | Tables and row types in database modules generate models.json, schema.sql, and a reviewable migrations/plan.sql. |
| Migrations | Plans in src/migrations/ run first. Then the database is reconciled with models.json. Plans never auto-DROP. |
| Repo | Supervised connection pools. Each has a name; one can own migrations. |
| Store adapters | Postgres and SQLite for SQL. ETS and Valkey for cache behind the same Cache API. |
| HTTP | Each request runs handle in its own process. Routes that need the program use Process.send or Process.call. |
| Channels | A channel module shares Topic, Up, Down, and the join reply with the SPA. One BEAM process holds each joined topic. |
| Html SSR | Html renders escaped markup. Server.html sends a document; Server.page embeds a shared TEA view in #app so the JS SPA can hydrate. |
Suggested folder structure
A full-stack app usually looks like this. Start with src/server/ alone if you only need HTTP, then add client/, database/, and migrations/ when you grow into them.
my_app/
selm.toml
src/
server/
Main.selm
client/
App.selm
Api.selm
Route.selm
Pages/
Views/
database/
Users.selm
Todos.selm
migrations/
20261031_sample_plan.selm
cli/
CLI/
tests/
build/selm.toml points at the server entry and an optional [client].entry. Database modules under src/database/ generate build/.../models.json and schema.sql. Migration plans live in src/migrations/ and run before reconcile. Open Examples and start from examples/03_todo_app when you want a working tree.