How it works

This page is the mental model. Once it clicks, the Language page and the examples will make much more sense.

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 when main is Fetch.Handler or Server.Program
  • erlang: HTTP servers, databases, websockets, and HTML rendered on the BEAM
  • atomvm: 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 memory
  • Msg: events that happened (a click, a timer, a message from another process)
  • update: turn a Msg into a new Model and maybe some commands
  • view / handle: turn the Model into HTML, or turn a Request into a Response

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.transaction and 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.

IdeaBEAM (`target = "erlang"`)Workers (`target = "javascript"`)
HTTP gateServer.application listener + request processesWorker fetch gate from Server.application
Named processProcess / actor under a SupervisorServer.durable singleton + Server.instance (idFromName(kind) / kind:id)
Gate TEAIn-memory program beside the listenerIsolate-local init / update / subscriptions; Server.send / snapshot
Call / castProcess.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 stateDatabase via Repo.transactionVersioned model blob + Server.Storage / Server.Env; optional SQLite (new_sqlite_classes / Database.Sql)
TimersSubscriptions / process timersServer.scheduleIn / cancelAlarm + onAlarm (getAlarm / alarmInfo)
Placement / HTTP-in-DON/AlocationHint / jurisdiction; forward + withFetch
Channelschannel module + binary wire + Cowboy WSServer.Socket.supervised + Server.Channel.define (explicit JSON; hibernatable DO WS)
CrashOTP restart strategyServer.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.

LayerWhat it does
Schema / modelsTables and row types in database modules generate models.json, schema.sql, and a reviewable migrations/plan.sql.
MigrationsPlans in src/migrations/ run first. Then the database is reconciled with models.json. Plans never auto-DROP.
RepoSupervised connection pools. Each has a name; one can own migrations.
Store adaptersPostgres and SQLite for SQL. ETS and Valkey for cache behind the same Cache API.
HTTPEach request runs handle in its own process. Routes that need the program use Process.send or Process.call.
ChannelsA channel module shares Topic, Up, Down, and the join reply with the SPA. One BEAM process holds each joined topic.
Html SSRHtml 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.