selm.toml reference

Every selm project needs a selm.toml at its root. It names the package, picks a compile target, lists source folders, and declares dependencies. Files use the TOML format.

A typical app

selm init writes a small Hello world manifest. A fuller Erlang app with a browser client and Postgres looks like this:


name = "todo"
target = "erlang"
source-directories = ["src/server", "src/database"]

[dependencies]
cowboy = "~> 2.20.0"
thoas = "~> 1.2.0"
ui = { path = "../ui" }

[client]
entry = "src/client/App.selm"

[features]
database = ["postgres"]

Runtime values such as listen ports and database passwords live in your Selm source, not here. See Configuration.

Project metadata

These keys describe the package. Day-to-day apps can omit most of them. selm publish and selm release need several of them.

name


name = "my_package"

name is the package and OTP application name. Optional for local work. Required for selm publish and selm release.

version


version = "1.0.0"

version is a semantic MAJOR.MINOR.PATCH string. Optional for local work. Required for selm publish and selm release. selm bump updates it from an API diff against the latest Hex release.

description


description = "Shared view modules for Selm apps"

A short summary of the package. Optional unless you publish to Hex.

licences


licences = ["MIT"]

SPDX licence identifiers for the package. Optional unless you publish to Hex. Publishing also expects a LICENSE, LICENCE, or NOTICE file in the project root.

repository


repository = "https://github.com/example/my_package"

URL of the source repository. Optional. Shown on Hex and used for release tag hints after publish.

links


[links]
docs = "https://example.com/my_package"
changelog = "https://example.com/changelog"

Extra named URLs for Hex metadata and generated docs. Keys are link titles; values are hrefs.

Compilation

target


target = "erlang"

target picks what selm make builds. Accepted values are "erlang" (default), "javascript", and "atomvm". Erlang builds servers, databases, and SSR. JavaScript builds browser apps. AtomVM builds firmware for microcontroller boards.

source-directories


source-directories = ["src"]

source-directories is required and must be non-empty. Selm loads .selm (and legacy .elm) from these folders and from path dependencies. When [features] database is set, src/migrations is added automatically if it exists. src/cli and tests are added the same way when those folders exist.

Dependency management

dependencies


[dependencies]
cowboy = "~> 2.20.0"
thoas = ">= 1.2.0 and < 2.0.0"
"elm-explorations/webgl" = "1.1.3"

Packages this project needs. Hex names are a single segment (cowboy). Community Elm packages use author/project and an exact version or Elm range. Client platform modules such as Browser and Html ship with selm on JavaScript and [client] builds, so you do not list them.

Path dependencies


ui = { path = "../ui" }

A local package is another folder with its own selm.toml. The path must be relative and stay inside the workspace jail (nearest .git ancestor, or a capped parent of the project). Absolute paths and home-directory shortcuts are refused. Import modules by name after you declare the path.

Private Hex packages


secret = { version = "~> 1.0", organization = "acme" }

Organization packages use a table with version and organization. Set HEX_API_KEY or SELM_HEX_API_KEY in the environment. selm deps and selm make resolve versions into selm.lock.

More detail on locks, NIFs, and publishing lives on Packages.

Client SPA

client.entry


[client]
entry = "src/client/App.selm"

On an Erlang project, [client].entry is a .selm Browser app that selm make compiles beside the server into build/client/app.js. If you omit entry and src/client/Pages/Todos.selm exists, that file is used as a fallback.

Features

features.database


[features]
database = ["postgres", "sqlite"]

[features] database turns on the database subsystem and lists which engines this project installs or starts: postgres, sqlite, ets, and valkey. Each Repo in source still chooses its own engine. postgres lets selm serve create the local selm database. sqlite needs the esqlite Hex dependency. ets and valkey install nothing. An empty list (database = []) enables the subsystem with no engines yet. Without the key, database module, migration module, and Repo do not resolve. Not allowed when target = "atomvm".

Distribution

distribution.cookie


[distribution]
cookie = "secret"

Cookie for a named BEAM node. There is no default. selm run, selm serve, and selm console also accept --cookie or SELM_COOKIE. A packaged release ignores this key and requires SELM_COOKIE when you start bin/<name>.

Native builds

native.allow


[native]
allow = ["my_nif"]

Hex packages with NIFs run publisher rebar3 scripts. Selm adapters such as esqlite are allowed automatically when listed under [dependencies]. Any other NIF package needs an explicit name here.

AtomVM

When target = "atomvm", you must set an [atomvm] table. Other targets must not include it.

atomvm.family and atomvm.board


[atomvm]
family = "esp32"
board = "esp32-s3"

family is "rp2" or "esp32". board must match that family. RP2 boards: pico, pico_w, pico2, pico2_w. ESP32 boards include esp32, esp32-s2, esp32-s3, esp32-c3, esp32-c6, and related variants. Use selm device to build, flash, and watch.

atomvm.crash_retries


[atomvm]
family = "rp2"
board = "pico"
crash_retries = 3

How many times Device.program may crash before the VM stops. Defaults to 3. Set crash_retries = "infinity" to never stop. Only a non-negative integer or the string "infinity" is accepted.