Differences from Elm

If you already know Elm, most of selm will feel familiar: modules, types, records, The Elm Architecture, and Html. This page is only what we added or changed.

App modules are .selm. Community packages you download from the Elm registry under project elm-stuff stay .elm.

Packages: the core stack is built in

In Elm, every app lists elm/core, elm/browser, elm/html, and friends in elm.json. In selm, those packages ship with the compiler as selm/core, selm/browser, selm/html, and the rest of the client platform. Browser code imports Browser, Html, Http, Json.Decode, Json.Decode.Pipeline, Random, Url, Time, Bytes, File, and Parser with nothing in [dependencies], and builds never download them.

A browser app's selm.toml can be this short:

target = "javascript"
source-directories = ["src"]

List only community packages, such as elm-explorations/webgl. Those still come from the Elm registry. Porting an Elm app? Leftover "elm/core" = "1.0.5" style lines are ignored, so you can delete them when convenient.

Shared names are not always the same API. BEAM Time uses Utc / getZone / formatIso; the client platform keeps Elm's utc / here / getZoneName. BEAM Process uses Subject / call / listen; the client platform keeps Elm's Id / spawn / kill. BEAM File is filesystem read / write; the client platform keeps Elm's browser File / File.Select. BEAM Random.generate is a Task; on JS it is a Cmd. Do not assume the stdlib catalog's BEAM Time, Process, or File surface when you write browser code.

Pattern forms (both targets)

selm keeps Elm's exhaustive case, and adds a few forms that Elm lacks. They work on JavaScript and Erlang; the JS pipeline desugars them.

OR-patterns share one branch across constructors. Alternatives must bind the same variable names:

case status of
  Pending | Loading ->
    "wait"

  Ready | Failed ->
    "go"

A guard adds a Bool after the pattern. Guarded branches do not count toward exhaustiveness, so you still need an unguarded branch or _:

case Server.jsonField req "title" of
  Just title if String.trim title /= "" ->
    createTodo title

  _ ->
    Server.empty 400 []

Record and tuple patterns can match field values directly, and partial records are allowed:

case user of
  { age = 18, active = True, name } ->
    name

  { name } ->
    name

case ( Server.jsonField req "id", Server.jsonField req "completed" ) of
  ( Just id, Just completed ) ->
    toggle id completed

  _ ->
    Server.empty 400 []

Binary patterns take apart a Bytes value field by field, like Erlang and Gleam. Segments are int by default (8 bits, unsigned, big-endian); add options such as 16, signed, little, float, or bytes-size(len) after a :. A bytes segment with no size takes the rest and must come last:

case input of
  << "PNG", version:8, len:16-little, payload:bytes-size(len), rest:bytes >> ->
    "png v" ++ String.fromInt version

  << flag:1, level:7 >> ->
    "flags"

  _ ->
    "unknown"

Sub-byte segments are fine, but the whole pattern must add up to whole bytes. A binary pattern can always fail, so a case needs a _ branch. On JavaScript, int segments are limited to 53 bits.

The Language tour covers OR-patterns, guards, and value-matching records. Binary patterns have their own tour step.

JS-only: WebGL shaders

On target = "javascript", [glsl| … |] blocks work the Elm way: selm extracts attribute / uniform / varying decls and links elm-explorations/webgl (plus elm-explorations/linear-algebra as needed). Depend on those packages in selm.toml like any other community Elm package. On the BEAM target, shader expressions are rejected at typecheck (they are not an unconstrained type).

vertexShader : Shader Vertex Uniforms { vcolor : Vec3 }
vertexShader =
    [glsl|
attribute vec3 position;
attribute vec3 color;
uniform mat4 perspective;
varying vec3 vcolor;

void main () {
    gl_Position = perspective * vec4(position, 1.0);
    vcolor = color;
}
|]

WebGL is not available on Erlang or AtomVM. Worked example: examples/09_webgl_triangle.

BEAM-only language forms

These syntaxes are for the Erlang target. The JavaScript compiler rejects migration modules, erlang/elixir FFI, and := bindings. A database module on JS keeps shared types and JSON codecs; tables and Transaction callables are stripped.

  • := binds a resource the runtime owns for you (a table, a sequence, a checked-out row)
  • database module declares tables, row security, indexes, and transactional functions
  • migration module holds ordered schema plans (rename, type change, raw SQL)
  • erlang "mod" "fun" and elixir "Mod" "fun" bind BEAM libraries; the Elm port keyword is not supported here

channel module is how you declare typed websockets shared by the server and the SPA. Details and examples live on the Language page.

Html.Attributes.label and span

Html.Attributes.label and Html.Attributes.span are omitted on purpose, matching upstream elm/html. Those names clash with the Html.label and Html.span node helpers when both modules are in scope. The JS hard-stack copies the same commented stubs as elm/html 1.0.0; do not restore them until Elm does.

Workarounds that stay portable: use Html.Attributes.attribute "label" ... / attribute "span" ..., or rename at the import site. On the BEAM SSR Html.Attributes module the surface is already the thin attribute / style API, so the same attribute helpers apply.

What stays the same

  • The Elm Architecture: Model, Msg, init, update, subscriptions, view
  • Modules, imports, exposing lists, type aliases, and custom types
  • Records, tuples, lists, pipes, and let expressions
  • Html and Html.Attributes for views (on JS as an SPA; on the BEAM as SSR), with the label / span attribute omission above
  • [glsl| … |] shaders on the JS target (same as Elm + elm-explorations/webgl)