Elm 0.19.3: install, build and run headlessly

A download of 15,126,132 bytes holds the whole Elm compiler. In this lesson’s recorded sessions it became one program of 61,507,360 bytes, which turned a 58-line program into a JavaScript file of 65,875 bytes, and Node.js ran that file with no browser at all and printed a receipt for 6,750 paise.

Here you install Elm 0.19.3 and check the download, start a project and read where its package versions are kept, compile it with and without --optimize, run it headlessly through a port, and then weigh what Elm’s compiler checks for you against what that costs, so you can say where Elm fits and where it does not.

Elm is one program, and you check it before you run it

The 0.19.3 release on GitHub offers five binaries and two installers. For a Mac with Apple silicon the file is elm-0.19.3-mac-arm.gz, 15,126,132 bytes, and the release page lists its SHA-256 digest beside it. The guide points Mac and Windows users to an installer; the compiler’s own install notes for macOS do the same job in four commands: download with curl, gunzip, chmod +x, and a move into a folder on PATH. Follow them, with the two checks that send you back a step:

The recorded session starts on a computer with Node.js and no Elm, with the file that curl -L -o elm.gz … saved. Each $ line is a command you would type, and below it is what the command printed:

"""Installs Elm 0.19.3 from its GitHub release on a computer that has Node.js and no Elm, checks the download against
the SHA-256 digest that the release page lists beside the file, and reads the versions (session.py plays it).

Downloading needs the network, which the session keeps switched off, so it starts with the file that
curl -L -o elm.gz https://github.com/elm/compiler/releases/download/0.19.3/elm-0.19.3-mac-arm.gz saved. elm-test comes
from npm (npm install --global elm-test@0.19.3-0 on a computer with a network)."""

from session import download, run

download("elm-0.19.3-mac-arm.gz", saved_as="elm.gz")
run("""
! command -v elm
wc -c < elm.gz
echo "a426e47d14cba0588aa81475adc32ba24bbf045209d0c560d0a89a5c4f3c34d0  elm.gz" | shasum -a 256 -c
gunzip elm.gz
chmod +x elm
mkdir -p $HOME/.local/bin
mv elm $HOME/.local/bin/
export PATH=$HOME/.local/bin:$PATH
command -v elm
elm --version
wc -c < $HOME/.local/bin/elm
node --version
elm-test --version
""", elm_on_path=False)

$ command -v elm
[exit status 1]
$ wc -c < elm.gz
 15126132
$ echo "a426e47d14cba0588aa81475adc32ba24bbf045209d0c560d0a89a5c4f3c34d0  elm.gz" | shasum -a 256 -c
elm.gz: OK
$ gunzip elm.gz
$ chmod +x elm
$ mkdir -p $HOME/.local/bin
$ mv elm $HOME/.local/bin/
$ export PATH=$HOME/.local/bin:$PATH
$ command -v elm
~/.local/bin/elm
$ elm --version
0.19.3
$ wc -c < $HOME/.local/bin/elm
 61507360
$ node --version
v24.21.0
$ elm-test --version
0.19.3-0

command -v elm failed first: nothing called elm was on PATH. shasum -a 256 -c read one line, the published digest and a file name, worked out the digest of elm.gz and printed OK because the two were equal. gunzip replaced elm.gz with elm, which chmod +x made runnable. The install notes move it into /usr/local/bin with sudo; the session uses ~/.local/bin, a folder of your own, and puts it first on PATH, so command -v elm names that file. Unpacked, the compiler is 61,507,360 bytes, about four times the download, and it holds elm make, elm install, elm repl and elm reactor in one file.

The last three lines are this module’s toolchain pinstoolchain pin: The exact version of the compiler, interpreter or SDK that an example was built and run with, such as Tcl 9.0.4 or the .NET SDK 10.0.401. Another version may print something else for the same file. More in “How the Language Atlas works”: 0.19.3, Node.js v24.21.0, which runs the compiled programs and elm repl, and 0.19.3-0 for elm-test, the test runner, which is not part of the compiler and comes from npm.

elm init writes elm.json, and only the first build needs the package site

elm init writes the one file every Elm project has, elm.json, and a src folder. To fill in the versions it needs the list of every published package, which comes from package.elm-lang.org. The session runs it twice with the network switched off: first with an empty package cache in ~/.elm, as on a computer that has never built Elm, then with the cache a computer has after its first builds. Both times elm init asks before it writes anything, and the session answers y:

"""Creates a project with elm init twice: first on a computer whose package cache, ~/.elm, is empty, then with the cache
that a computer has after it has built a project once, both with the network switched off (session.py plays it).
elm init asks before it writes elm.json, and the session answers y."""

from session import cache, run

run("""
mkdir first
cd first
! elm init
""", stdin="y\n")
cache()
run("""
# ~/.elm now holds the packages that the first builds downloaded
elm init
ls
cat elm.json
ls $HOME/.elm/0.19.3/packages/elm
""", stdin="y\n")

$ mkdir first
$ cd first
$ elm init
Hello! Elm projects always start with an elm.json file. I can create them!

Now you may be wondering, what will be in this file? How do I add Elm files to
my project? How do I see it in the browser? How will my code grow? Do I need
more directories? What about tests? Etc.

Check out <https://elm-lang.org/0.19.3/init> for all the answers!

Knowing all that, would you like me to create an elm.json file now? [Y/n]: -- PROBLEM LOADING PACKAGE LIST ------------------------------------------------

I need the list of published packages before I can start initializing projects,
so I tried to fetch:

    https://package.elm-lang.org/all-packages

But my HTTP library is giving me the following error message:

    ConnectionFailure Network.Socket.getAddrInfo (called with preferred socket type/protocol: AddrInfo {addrFlags = [AI_ADDRCONFIG], addrFamily = AF_UNSPEC, addrSocketType = Stream, addrProtocol = 0, addrAddress = 0.0.0.0:0, addrCanonName = Nothing}, host name: "package.elm-lang.org", service name: "443"): does not exist (nodename nor servname provided, or not known)

Are you somewhere with a slow internet connection? Or no internet? Does the link
I am trying to fetch work in your browser? Maybe the site is down? Does your
internet connection have a firewall that blocks certain domains? It is usually
something like that!
[exit status 1]
# ~/.elm now holds the packages that the first builds downloaded
$ elm init
Hello! Elm projects always start with an elm.json file. I can create them!

Now you may be wondering, what will be in this file? How do I add Elm files to
my project? How do I see it in the browser? How will my code grow? Do I need
more directories? What about tests? Etc.

Check out <https://elm-lang.org/0.19.3/init> for all the answers!

Knowing all that, would you like me to create an elm.json file now? [Y/n]: Okay, I created it. Now read that link!
$ ls
elm.json
src
$ cat elm.json
{
    "type": "application",
    "source-directories": [
        "src"
    ],
    "elm-version": "0.19.3",
    "dependencies": {
        "direct": {
            "elm/browser": "1.0.2",
            "elm/core": "1.0.5",
            "elm/html": "1.0.1"
        },
        "indirect": {
            "elm/json": "1.1.4",
            "elm/time": "1.0.0",
            "elm/url": "1.0.0",
            "elm/virtual-dom": "1.0.5"
        }
    },
    "test-dependencies": {
        "direct": {},
        "indirect": {}
    }
}
$ ls $HOME/.elm/0.19.3/packages/elm
browser
bytes
core
html
json
random
time
url
virtual-dom

The first try stopped with PROBLEM LOADING PACKAGE LIST and exit status 1: it could not fetch all-packages, and it wrote nothing. The second worked offline, because ~/.elm already held the list and the packages. The compiler keeps that cache in ~/.elm, or in the folder that the ELM_HOME variable names, and every project on the computer shares it: here it also holds bytes and random, packages that only a later lesson’s tests use.

Read elm.json from the top. "type": "application" says this is a program, not a package. "source-directories" says where the modules are. "elm-version" is the exact compiler, 0.19.3. Then come the dependencies: three direct ones, which your code may import, and four indirect ones, which those three need. Every one has a single exact version: elm/core is 1.0.5, not a range. The compiler’s documentation for this file says that the exact versions make elm.json double as a lock fileA file that records the exact version of every package a build uses, so that every later build gets the same ones. An Elm application's elm.json is one; npm keeps a separate package-lock.json., and that the indirect ones are listed so that builds are reproducible and you can see everything you depend on. A package’s own elm.json is different: elm/browser’s, in the cache, asks for ranges such as "1.0.0 <= v < 2.0.0", which an application then resolves to one version each. Step through what happened, and what a computer with a network does:

elm make writes one JavaScript file, and the optimize flag changes little on a small one

orders/ is a project with the elm.json that elm init wrote and one module, src/Orders.elm: two lines of an order priced in paise, added up and sent out as a receipt. The session builds it twice, plainly and with --optimize, measures each file and runs it:

"""Builds the Orders worker without and with --optimize, runs each build under Node.js through the port, measures both
files and shows the two lines that end the compiled file; late.cjs then subscribes too late (session.py plays it)."""

from session import cache, run

cache()
run("""
cd orders
elm make src/Orders.elm --output=build/orders.js
wc -c < build/orders.js
node run.cjs
elm make src/Orders.elm --optimize --output=build/orders.js
wc -c < build/orders.js
gzip -9 < build/orders.js | wc -c
tail -n 2 build/orders.js
node run.cjs
node late.cjs
""")

$ cd orders
$ elm make src/Orders.elm --output=build/orders.js
Dependencies ready!
Success! Compiled 1 module.

    Orders ───> build/orders.js
$ wc -c < build/orders.js
   65875
$ node run.cjs
Compiled in DEV mode. Follow the advice at https://elm-lang.org/0.19.3/optimize for better performance and smaller assets.
chai    2 x ₹12.00  ₹24.00
samosa  3 x ₹14.50  ₹43.50
total               ₹67.50
$ elm make src/Orders.elm --optimize --output=build/orders.js
Success!

    Orders ───> build/orders.js
$ wc -c < build/orders.js
   65308
$ gzip -9 < build/orders.js | wc -c
   15746
$ tail -n 2 build/orders.js
_Platform_export({'Orders':{'init':$author$project$Orders$main(
	$elm$json$Json$Decode$succeed(0))(0)}});}(this));
$ node run.cjs
chai    2 x ₹12.00  ₹24.00
samosa  3 x ₹14.50  ₹43.50
total               ₹67.50
$ node late.cjs
messages that reached a subscriber added in a timer: 0

The plain build printed Dependencies ready! and Success! Compiled 1 module. and wrote build/orders.js, 65,875 bytes. Running it printed a warning first: Compiled in DEV mode, with a link to the compiler’s advice on optimising. The second build printed only Success!: the module was already compiled in elm-stuff, so there was nothing new to compile. Its file is 65,308 bytes, 567 bytes or 0.9 % smaller, 15,746 bytes after gzip -9, and it printed the same receipt without the warning.

So what does --optimize do? elm make --help says it shortens record field names and unboxes values, and the post that introduced it in 0.19 says the renaming tends to make files 5 % to 10 % smaller. Orders is too small to show that: most of its file is the runtime and the core functions it calls, and it has three record fields of its own. Two things happen in every build, optimised or not. The types are checked before anything is written, and dead code eliminationdead code elimination: A compiler step that leaves out every function a program can never call. Elm does it in every build, function by function, across the application and all its packages, because Elm functions cannot be redefined while the program runs. drops every function that main cannot reach, which the same post says works across all packages because each one on the package site is written entirely in Elm. The big saving is a minifier, which the compiler’s notes on optimising add as a second step; the project lesson of this module measures it. Step through one build:

Platform.worker runs Elm without a page, and a port carries the result out

A browser program draws a view. Orders has none: its main is a Platform.workerPlatform.worker: The kind of Elm program that has no view, only init, update and subscriptions. It runs under Node.js or in a page without drawing anything and talks to JavaScript through ports, so Elm code can run headlessly., which the core library’s documentation calls a program with no user interface. It takes three functions: init starts it, update handles messages and subscriptions says which outside events it listens to. Its only way to show anything is a portport: A typed channel between Elm and JavaScript, declared with the port keyword in a port module. A port that returns Cmd sends values out to JavaScript subscribers; one that returns Sub brings values sent from JavaScript in as messages.: port report : String -> Cmd msg declares a command that sends a string to JavaScript, and the first line, port module Orders, is what allows a module to declare one:

port module Orders exposing (main)

{-| Adds up a small order priced in paise and sends a receipt out through the
port `report`. A Platform.worker has no view, so Node.js can run it.
-}


port report : String -> Cmd msg


type alias Line =
    { item : String
    , paise : Int
    , quantity : Int
    }


order : List Line
order =
    [ { item = "chai", paise = 1200, quantity = 2 }
    , { item = "samosa", paise = 1450, quantity = 3 }
    ]


lineTotal : Line -> Int
lineTotal line =
    line.paise * line.quantity


rupees : Int -> String
rupees paise =
    "₹" ++ String.fromInt (paise // 100) ++ "." ++ String.padLeft 2 '0' (String.fromInt (modBy 100 paise))


receipt : List Line -> String
receipt lines =
    let
        row line =
            String.padRight 8 ' ' line.item
                ++ String.fromInt line.quantity
                ++ " x "
                ++ rupees line.paise
                ++ "  "
                ++ rupees (lineTotal line)

        total =
            List.sum (List.map lineTotal lines)
    in
    String.join "\n" (List.map row lines ++ [ "total" ++ String.repeat 15 " " ++ rupees total ])


main : Program () () Never
main =
    Platform.worker
        { init = \_ -> ( (), report (receipt order) )
        , update = \_ model -> ( model, Cmd.none )
        , subscriptions = \_ -> Sub.none
        }

init ignores its flags and returns two things: the model, (), which holds nothing, and the command report (receipt order). update and subscriptions do nothing, since nothing ever sends this program a message. The JavaScript side is three lines of code:

// Starts the Orders worker of build/orders.js and prints what it sends through its port `report`.
const { Elm } = require('./build/orders.js');

const app = Elm.Orders.init();
app.ports.report.subscribe((text) => console.log(text));

Step through one run, the one the session recorded twice:

run.cjs uses CommonJS on purpose. The compiled file is one function called with this, and it puts Elm on that object, as the two lines that end build/orders.js show in the session: _Platform_export({'Orders': …}) and }(this));. Under require, this is the module’s exports, and in a browser <script> it is the window. Loaded as an ES module, from a folder whose package.json says "type": "module", the same file finds no this to put Elm on.

What the compiler checks for you, and what that costs

Elm’s homepage leads with no runtime exceptions, friendly error messages and great performance, and lists small assets and enforced semantic versioning among its features. Two of those you have now seen at work: a compiler that checks every type before it writes a line, and a build that keeps only what main reaches. The third is about packages. elm diff compares the types of two versions of a package, and the homepage says Elm uses that check to make every package follow semantic versioning, so a patch release cannot remove a function you call.

These checks come at a price, and the price is the border with JavaScript. Elm code reaches JavaScript only through flags at start-up, ports and custom elements, and every package on the package site is written in Elm, so an npm library is used by writing a port for it. The language also moves slowly and with care: the four releases of 0.19 changed the language once, at 0.19.0, and each later release says there are no language changes. Walk through them:

“No runtime exceptions” also has edges, and the next two lessons record them: modBy 0 stops a program with an error, and so does a value of the wrong type sent through a port. The rule holds inside your Elm code; at the border, you check.

So Elm fits front ends where wrong states and crashes cost more than a small ecosystem does: forms, flows with many steps, dashboards a team keeps for years. It can start small, because Browser.element takes over one node of an existing page, and the element documentation says many companies that use Elm began that way. Three questions about the work decide most of the choice; answer them in the table:

In short: a new front end with many states suits a whole Elm app; an existing app suits one Elm element that grows; and work that leans on many npm UI libraries stays easiest in JavaScript or TypeScript, or keeps those libraries behind ports.

Practise: print paise as rupees, then read elm.json

Two steps, in JavaScript, because the page runs JavaScript tests in your browser. The first writes the worker’s rupees function in JavaScript, digit for digit, so that you can check any amount the receipt might print without building Elm at all. The second reads the elm.json files of this lesson the way the compiler reads them: where each package is listed, which versions an application pins, and why a package’s own file, with its ranges, is not a lock file. Each step has sample tests and a first hint:

/** The amount `paise` as rupees with two digits after the dot: rupees(6750) is "₹67.50". */
export function rupees(paise) {
  // Replace this: dividing first gives "₹67.5" for 6750 and "₹0.05" only by luck.
  return '₹' + paise / 100;
}

import { test, assert } from 'mysmartcopilot:test';
import { rupees } from './rupees.mjs';

test('the three amounts of the receipt that Orders.elm printed', () => {
  assert.equal(rupees(1200), '₹12.00');
  assert.equal(rupees(4350), '₹43.50');
  assert.equal(rupees(6750), '₹67.50');
});

test('always two digits after the dot', () => {
  assert.equal(rupees(0), '₹0.00');
  assert.equal(rupees(5), '₹0.05');
  assert.equal(rupees(99), '₹0.99');
  assert.equal(rupees(100), '₹1.00');
  assert.equal(rupees(101), '₹1.01');
});

test('large amounts have no separators', () => {
  assert.equal(rupees(123456), '₹1234.56');
  assert.equal(rupees(1000000), '₹10000.00');
});

test('negative amounts and fractions of a paisa are refused', () => {
  assert.throws(() => rupees(-5), RangeError);
  assert.throws(() => rupees(12.5), RangeError);
});

/** Where the elm.json text `text` lists the package `name`: "direct", "indirect", "test-direct", "test-indirect" or null. */
export function whereListed(text, name) {
  // Replace this: it only looks at the direct dependencies.
  const json = JSON.parse(text);
  return name in json.dependencies.direct ? 'direct' : null;
}

/** Every package of an application's elm.json with its exact version, as [name, version] pairs sorted by name. */
export function pinned(text) {
  // Replace this: it forgets the indirect and test dependencies, and accepts a package's elm.json.
  const json = JSON.parse(text);
  return Object.entries(json.dependencies.direct);
}

import { test, assert } from 'mysmartcopilot:test';
import { whereListed, pinned } from './deps.mjs';

// The elm.json that elm init wrote in the lesson's session.
const app = JSON.stringify({
  type: 'application',
  'source-directories': ['src'],
  'elm-version': '0.19.3',
  dependencies: {
    direct: { 'elm/browser': '1.0.2', 'elm/core': '1.0.5', 'elm/html': '1.0.1' },
    indirect: { 'elm/json': '1.1.4', 'elm/time': '1.0.0', 'elm/url': '1.0.0', 'elm/virtual-dom': '1.0.5' },
  },
  'test-dependencies': { direct: {}, indirect: {} },
}, null, 4);

// The same file after elm-test init added the test runner's packages.
const withTests = JSON.stringify({
  ...JSON.parse(app),
  'test-dependencies': {
    direct: { 'elm-explorations/test': '2.2.1' },
    indirect: { 'elm/bytes': '1.0.8', 'elm/random': '1.0.0' },
  },
}, null, 4);

// elm/browser 1.0.2's own elm.json, from ~/.elm/0.19.3/packages/elm/browser/1.0.2/elm.json.
const browserPackage = JSON.stringify({
  type: 'package',
  name: 'elm/browser',
  version: '1.0.2',
  'elm-version': '0.19.0 <= v < 0.20.0',
  dependencies: {
    'elm/core': '1.0.0 <= v < 2.0.0',
    'elm/html': '1.0.0 <= v < 2.0.0',
    'elm/json': '1.0.0 <= v < 2.0.0',
    'elm/time': '1.0.0 <= v < 2.0.0',
    'elm/url': '1.0.0 <= v < 2.0.0',
    'elm/virtual-dom': '1.0.2 <= v < 2.0.0',
  },
  'test-dependencies': {},
}, null, 4);

test('direct and indirect dependencies of the session elm.json', () => {
  assert.equal(whereListed(app, 'elm/core'), 'direct');
  assert.equal(whereListed(app, 'elm/html'), 'direct');
  assert.equal(whereListed(app, 'elm/json'), 'indirect');
  assert.equal(whereListed(app, 'elm/virtual-dom'), 'indirect');
  assert.equal(whereListed(app, 'elm/http'), null);
});

test('test dependencies after elm-test init', () => {
  assert.equal(whereListed(withTests, 'elm-explorations/test'), 'test-direct');
  assert.equal(whereListed(withTests, 'elm/random'), 'test-indirect');
  assert.equal(whereListed(withTests, 'elm/core'), 'direct');
});

test('every package with its exact version, sorted by name', () => {
  assert.deepEqual(pinned(app), [
    ['elm/browser', '1.0.2'],
    ['elm/core', '1.0.5'],
    ['elm/html', '1.0.1'],
    ['elm/json', '1.1.4'],
    ['elm/time', '1.0.0'],
    ['elm/url', '1.0.0'],
    ['elm/virtual-dom', '1.0.5'],
  ]);
  assert.deepEqual(pinned(withTests).map(([name]) => name), [
    'elm-explorations/test',
    'elm/browser',
    'elm/bytes',
    'elm/core',
    'elm/html',
    'elm/json',
    'elm/random',
    'elm/time',
    'elm/url',
    'elm/virtual-dom',
  ]);
});

test('a package lists ranges, so pinned refuses it', () => {
  assert.throws(() => pinned(browserPackage), Error);
});

Then try the self-check on the five ideas of this lesson. It asks first about the idea you are least sure of, and explains every answer as soon as you choose it:

Interview questions

Warm-up (fresher to mid-level): Where does an Elm application record the versions of its packages, and what is ~/.elm for?

In elm.json. Its dependencies list every package the application uses, the direct ones that its code imports and the indirect ones that those need, each with one exact version, such as elm/core 1.0.5; test packages go in test-dependencies the same way. Because the versions are exact, the file is its own lock file: there is no second file to keep in step, and committing elm.json fixes the build. ~/.elm is the package cache, shared by every project on the computer: the list of published packages and the source and compiled form of each version downloaded so far. The ELM_HOME variable moves it. A fresh computer needs the network for its first elm init or build; once the cache holds the packages, both work offline, as the lesson’s second elm init did.

Two longer questions, one about a build that breaks in CI and one about choosing Elm:

Key takeaways

• Elm is one program: download the release file, check it against the digest the release page lists, unpack it and put it first on PATH; elm --version must print 0.19.3 before outputs can be compared with this module.
• An application’s elm.json names every direct and indirect package with one exact version, so it is its own lock file, while ~/.elm caches the packages for every project and lets later inits and builds run offline.
• elm make checks types, keeps only what main reaches and writes one JavaScript file; --optimize renamed record fields and saved 0.9 % of a 65,875-byte worker, and a minifier is the step that shrinks it.
• Platform.worker runs Elm with no view, and a port carries values out to JavaScript, so Node.js can run and check an Elm program headlessly once it subscribes right after init().
• Elm’s compiler rules out null and unhandled cases and enforces package versions, at the price of a border with JavaScript that you cross through flags, ports and custom elements, and check yourself.