Choosing Between Gleam Native and JavaScript Compilation Targets

You need to decide how to compile a Gleam program: to an Erlang/BEAM executable that runs on a server or command line, or to JavaScript that runs in a browser or Node.js. The wrong choice can force a rewrite later because switching targets changes build configuration and may require rewriting code that touches platform-specific APIs.

The useful takeaway is to choose the Erlang/BEAM target for command-line tools, background workers, and services that need direct system access. Choose the JavaScript target for browser front-ends or projects that must integrate with an existing JavaScript package. Benchmark the critical path before committing to either target.

The Decision and Constraints

Gleam compiles source code to one of two supported targets. The BEAM is the Erlang virtual machine that executes Gleam code compiled to the Erlang target. A native build in this context means a standalone executable or BEAM bytecode package produced by the Erlang target, not a machine-code binary compiled from Gleam directly.

Constraints to weigh before choosing:

• Deployment platform: server, CLI, browser, or Node.js
• Binary or bundle size: bandwidth, storage, and cold-start time
• Interoperability: Erlang/Elixir libraries versus JavaScript packages
• System access: files, processes, sockets, and native APIs
• Toolchain stability: maturity of the target in your installed Gleam version

Supported Targets at a Glance

Trade-offs

Erlang/BEAM target

Advantages: the BEAM VM provides lightweight processes and multi-core concurrency, and the resulting executable can call Erlang libraries and operating-system APIs directly. Startup is usually fast because there is no JavaScript engine warm-up.

Disadvantages: the executable or package is typically several megabytes, which matters for constrained environments. You must build on the same OS and architecture as the deployment target, or the executable will not run. Debugging may require external symbols or a separate debug build.

JavaScript target

Advantages: output runs anywhere JavaScript runs, integrates with npm packages, and source maps are generated automatically to simplify browser debugging. Bundles are often smaller than BEAM executables, which helps browser delivery.

Disadvantages: JavaScript output is still experimental in many Gleam releases and may change across minor versions. Some Gleam constructs, especially those relying on Erlang interop, may not translate correctly. Startup overhead and concurrency behavior depend on the JavaScript engine, which can be less deterministic than the BEAM scheduler.

Version and Feature Assumptions

Gleam documentation describes the Erlang target as mature and the JavaScript target as experimental. Because this can change between minor releases, verify your installed version before relying on either target for production. Run gleam --version and inspect gleam build --help to confirm which targets your toolchain accepts.

Concrete Validation: Compile Hello World to Both Targets

Run these commands in the project directory as an ordinary user. No root or administrator permissions are required. Replace <project-name> with your project identifier.

1. Create a new project:
2. gleam new <project-name>
3. Enter the project:
4. cd <project-name>
5. Edit src/<project-name>.gleam so the main function prints a message, for example:
6. pub fn main() {
io.println("Hello from Gleam")
}
7. Build for Erlang/BEAM:
8. gleam build --target erlang

Expected check: an executable appears under the dev/erlang/ directory. Running it should print Hello from Gleam. Risk: an executable built on Apple Silicon will not run on an x86_64 server without a matching build host or cross-compilation setup.

1. Build for JavaScript:
2. gleam build --target javascript

Expected check: the dev/javascript/ directory contains a JavaScript bundle and a corresponding .map source-map file. Inspect the map file to confirm source mapping is present. Risk: JavaScript output may omit or alter Gleam constructs that depend on Erlang-specific behavior.

Diagnostic Decision Checklist

• Deploying a CLI or long-running service? Choose Erlang/BEAM.
• Deploying to a browser? Choose JavaScript.
• Need direct file-system or process access? Choose Erlang/BEAM.
• Must integrate with an existing React or Node.js library? Choose JavaScript.
• Uncertain about performance? Build both targets from the same source and measure startup time and memory use on a representative workload.

Limitations and Verification

This is a conservative draft. The commands and directory layouts are illustrative and have not been executed against a live Gleam toolchain. Verify them with your installed version before using them in a pipeline.

Practical verification steps:

1. Run gleam --version and record the version.
2. Run gleam build --target erlang and gleam build --target javascript from the same source tree.
3. Run each output and confirm it prints the expected message.
4. Inspect the JavaScript output directory for a source-map file.
5. Compare file sizes and startup time for the two outputs.

Rollback is simple because these commands only create files inside the project directory. Delete the dev/ directory to remove build artifacts; no system-wide state is changed.

Recommended Default

Start with Erlang/BEAM for backend tooling, services, and CLIs. Start with JavaScript for browser front-ends. If a critical code path is performance-sensitive, benchmark both targets on the actual deployment hardware before making the final decision.