Skip to main content

​
Installation

Arc is currently only available as source code. You’ll need to build it from the GitHub repository using Gleam and Erlang.

​
Prerequisites

Arc requires the following tools to be installed:

​
Erlang/OTP

Arc runs on the BEAM virtual machine, so you need Erlang/OTP installed.
Recommended version: Erlang/OTP 26 or later
1

Check if Erlang is installed

erl -version
You should see output like:
Erlang (SMP,ASYNC_THREADS) (BEAM) emulator version 14.2
2

Install Erlang (if needed)

brew install erlang

​
Gleam

Arc is written in Gleam, a type-safe functional language that compiles to Erlang.
Recommended version: Gleam 1.0 or later
1

Check if Gleam is installed

gleam --version
You should see output like:
gleam 1.0.0
2

Install Gleam (if needed)

brew install gleam
See the official Gleam installation guide for more options.

​
Git

You’ll need Git to clone the Arc repository: 
git --version

​
Building Arc

Once you have the prerequisites installed, you can build Arc:
1

Clone the repository

git clone https://github.com/your-org/arc.git
cd arc
2

Build the project

Gleam will automatically download dependencies and compile the project:
gleam build
The first build downloads these dependencies:
  • gleam_stdlib - Gleam’s standard library
  • gleeunit - Testing framework (dev dependency)
  • simplifile - File system utilities (dev dependency)
Subsequent builds are incremental and much faster.
3

Verify the installation

Test that Arc works by running the REPL:
gleam run
You should see the Arc banner:
arc -- JavaScript on the BEAM
Run /help for commands, Ctrl+C to exit.

>
Try a simple expression:
> 1 + 2
3
> Arc.self()
<0.123.0>
Press Ctrl+C to exit.

​
Running Arc programs

Arc can run JavaScript files or start an interactive REPL.

​
Run a JavaScript file

gleam run path/to/file.js
Example: 
gleam run examples/simple.js

​
File types

Arc supports two file types:
  • ES Modules (.js) - Default. Files are treated as ES modules with import/export
  • CommonJS scripts (.cjs) - Legacy script mode without module semantics
Most examples use ES module syntax. Use .cjs extension only if you need classic script semantics.

​
Interactive REPL

Start the REPL with no arguments: 
gleam run

​
Evaluate expressions

Use the -p flag to evaluate an expression and exit: 
gleam run -- -p "1 + 2"
Output: 
3

​
Development workflow

If you’re developing Arc itself:
1

Run tests

gleam test
This runs Arc’s test suite including parser, compiler, VM, and runtime tests.
2

Run test262 (optional)

Arc tracks ECMAScript spec compliance using the official Test262 suite:
TEST262=1 gleam test
Full test262 execution tests take a long time to run. Use parser-only mode for faster feedback during development.
3

Type check without building

gleam check
This is much faster than a full build and catches type errors early.
4

Format code

gleam format
Gleam has an opinionated formatter. Always format before committing.

​
Project structure

Once built, the Arc project has this structure: 
arc/
├── src/
│   └── arc/
│       ├── arc.gleam          # Main entry point & REPL
│       ├── parser.gleam       # JavaScript parser
│       ├── compiler.gleam     # Bytecode compiler
│       ├── lexer.gleam        # Tokenizer
│       ├── ast.gleam          # AST definitions
│       ├── module.gleam       # ES module system
│       └── vm/
│           ├── vm.gleam       # Bytecode interpreter
│           ├── value.gleam    # JavaScript value representation
│           ├── heap.gleam     # Heap management
│           ├── opcode.gleam   # Bytecode instruction set
│           └── builtins/      # Built-in JavaScript APIs
│               ├── arc.gleam  # Arc.spawn, Arc.send, etc.
│               ├── array.gleam
│               ├── object.gleam
│               ├── string.gleam
│               ├── math.gleam
│               └── ...
├── examples/                  # Example programs
│   ├── simple.js
│   ├── counter_actor.js
│   ├── concurrent.js
│   ├── ping_pong.js
│   └── ring.js
├── test/                      # Test suite
├── gleam.toml                 # Project configuration
└── README.md

​
Troubleshooting

​
”gleam: command not found”

Gleam is not installed or not in your PATH. Follow the Gleam installation steps above.

​
”erl: command not found”

Erlang is not installed or not in your PATH. Follow the Erlang installation steps above.

​
Build errors about missing dependencies

Try removing the build cache and rebuilding: 
rm -rf build/
gleam build

​
REPL crashes or hangs

This is expected - Arc is highly experimental. File an issue on GitHub with:
  • The JavaScript code you ran
  • Error messages or output
  • Your Erlang and Gleam versions

​
Test262 tests fail

Arc is not fully spec-compliant yet. Many test262 tests are expected to fail. Check the conformance chart in the repository for current status.

​
Next steps

Quickstart

Run your first Arc program

Core concepts

Learn about Arc’s architecture

API reference

Learn the Arc API

Actor programming

Write concurrent programs

Build docs developers (and LLMs) love

Get started for freeTalk to us