Popcorn is a library that allows you to run client-side Elixir in browsers, with JavaScript interoperability
Popcorn is early stages and may break. Please report an issue if it does. Contributions are very welcome, but please open an issue before committing too much effort.
Under the hood, Popcorn runs AtomVM, a tiny Erlang VM.
The examples are hosted at popcorn.swmansion.com, and the source code is in the examples directory.
Note: Popcorn currently only works OTP 26.0.2 and Elixir 1.17.3. We're working to lift this requirement.
Popcorn requires just a few short steps to setup. Firstly, add the project to dependencies and ensure you have an application start callback:
# mix.exs
def application do
[
extra_applications: [],
mod: {MyApp.Application, []}
]
end
def deps do
[
{:popcorn, "~> 0.1.0"}
]
endThe application should start a worker process:
# lib/my_app/application.ex
defmodule MyApp.Application do
use Application
@impl true
def start(_type, _args) do
children = [
MyApp.Worker
]
opts = [strategy: :one_for_one, name: MyApp.Supervisor]
Supervisor.start_link(children, opts)
end
endA minimal worker should register itself using Popcorn.Wasm.register/1:
# lib/my_app/worker.ex
defmodule MyApp.Worker do
use GenServer
@process_name :main
def start_link(args) do
GenServer.start_link(__MODULE__, args, name: @process_name)
end
@impl true
def init(_init_arg) do
Popcorn.Wasm.register(@process_name)
IO.puts("Hello from WASM!")
state = %{}
{:ok, state}
end
endThen, configure the directory to output static artifacts:
# config/config.exs
import Config
config :popcorn, out_dir: "static/wasm"Finally, run mix deps.get and mix popcorn.cook. The latter will generate WASM artifacts in the static/wasm directory. Add a simple HTML file that will load it:
<!-- index.html -->
<html>
<script type="module">
import { Popcorn } from "./wasm/popcorn.js";
await Popcorn.init({ onStdout: console.log });
</script>
<body></body>
</html>The easiest way to host the page is to generate a simple HTTP server script with mix popcorn.simple_server and run it with elixir server.exs. Then, at http://localhost:4000, you should see Hello from WASM printed in the console.
The webpage can also be hosted with any HTTP static file server, but it must add the following HTTP headers:
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
Otherwise, browsers refuse to run WASM.
Popcorn also ships with a server that supports live reloading. It can be generated with mix popcorn.dev_server and run with elixir dev_server.exs.
The index.html requires an extra line to load the required JavaScript.
<!-- index.html -->
<html>
<script type="text/javascript" src="/dev_server.js"></script>
<script type="module">
import { Popcorn } from "./wasm/popcorn.js";
await Popcorn.init({ onStdout: console.log });
</script>
<body></body>
</html>Popcorn runs AtomVM under the hood, and therefore it needs to either download precompied artifacts or compile it from source. The default configuration should work out of the box, but you can change it to use a different version of AtomVM.
Precompiled artifacts are downloaded during Popcorn compilation, from the source specified with runtime config key, for example:
config :popcorn, runtime: [
{:url, "https://atomvm/wasm/url", target: :wasm},
{:path, "/path/to/atomvm/unix", target: :unix}
]If you want to build the runtime from source, run mix popcorn.build_runtime --target <unix|wasm>. Make sure you have AtomVM dependencies installed. Then, configure the runtime as follows:
config :popcorn, runtime: {:path, "popcorn_runtime_source/artifacts/$target"}We use mise to manage dependencies. Install it and install deps and dev tools with:
mise installThen, you should setup pre-commit hooks using lefthook:
lefthook installPopcorn tests can be run either on WASM via Playwright or natively on UNIX. To run them on WASM, run
TARGET=wasm mix testTo run tests on UNIX, use
mix popcorn.build_runtime --target unixto build AtomVM from source. Make sure you have AtomVM dependencies installed. Then, run
mix testPopcorn is created by Software Mansion.
Since 2012 Software Mansion is a software agency with experience in building web and mobile apps as well as complex multimedia solutions. We are Core React Native Contributors and experts in live streaming and broadcasting technologies. We can help you build your next dream product – Hire us.
Copyright 2025, Software Mansion
Licensed under the Apache License, Version 2.0
