gleam

---
name: gleam
description: Use when building type-safe, concurrent applications on the Erlang BEAM or compiling to JavaScript with a friendly functional language.
source: https://gleam.run/documentation/
generated: 2026-07-02T18:41:46.923Z
category: language
audience: engineers
---

## When to use

- Writing fault-tolerant, concurrent backends on the BEAM with static types
- Targeting both Erlang and JavaScript from one statically typed codebase
- Interoperating with existing Erlang/Elixir/OTP libraries from typed code
- Wanting an ML-style type system with no nulls and exhaustive pattern matching

## Key concepts

### BEAM target

Gleam compiles to Erlang by default, running on the BEAM VM with OTP supervision, lightweight processes, and message passing. It can also compile to JavaScript with --target javascript.

### Result and Option

Gleam has no null and no exceptions for normal flow. Fallible operations return Result(value, error) and optional values use Option(a) (Some/None). The use expression and try-style chaining handle them ergonomically.

### Pattern matching with case

case expressions destructure values and must be exhaustive; the compiler errors if a variant is unhandled. This makes adding a custom type variant surface every place needing an update.

### Pipe operator |>

x |> f(y) calls f(x, y), threading a value through a sequence of functions for readable left-to-right data transformations.

### use expression

use desugars callback-passing functions into flat code, replacing nested closures. Common for Result chaining: use value <- result.try(operation).

### Custom types

Algebraic data types declared with pub type Name { Variant(fields) }. They model records and tagged unions; labelled fields enable named arguments at the call site.

## API reference

```
gleam new <name>
```

Scaffold a new Gleam project with gleam.toml, src/, and test/ directories.

```
gleam new my_app
cd my_app
```

```
gleam run
```

Compile and run the project's main function (the module matching the project name).

```
gleam run
```

```
gleam test
```

Compile and run tests; the default test runner is gleeunit.

```
gleam test
```

```
gleam build
```

Type-check and compile the project to the configured target without running it.

```
gleam build --target javascript
```

```
gleam add <package>
```

Add a Hex dependency and update gleam.toml and the lockfile.

```
gleam add gleam_http gleam_json
```

```
gleam format
```

Format all source files using the canonical Gleam formatter.

```
gleam format
```

```
gleam deps download
```

Fetch dependencies declared in gleam.toml without building.

```
gleam deps download
```

```
pub fn main() { ... }
```

Program entry point; functions and types must be marked pub to be visible outside the module.

```
import gleam/io
import gleam/list

pub fn main() {
  [1, 2, 3]
  |> list.map(fn(x) { x * 2 })
  |> list.fold(0, fn(acc, x) { acc + x })
  |> io.debug
}
```

```
case subject { pattern -> expr }
```

Exhaustive pattern matching expression that returns a value.

```
case result {
  Ok(value) -> value
  Error(_) -> 0
}
```

## Gotchas

- There is no null and no implicit conversions; mixing Int and Float requires explicit conversion (int.to_float).
- case expressions must be exhaustive or the compiler refuses to build.
- Int uses + and Float uses +.; using the wrong operator for the type is a type error.
- All values are immutable; there is no mutation, so update records with the .. spread syntax in a new value.
- External Erlang/JS code must be declared with @external and is unchecked at the boundary, so wrap FFI carefully.
- Functions and types are private by default; forgetting pub makes them invisible to other modules and tests.
- JavaScript and Erlang targets differ in available stdlib and integer semantics; test the target you ship.
- Labelled arguments are positional unless you use the label name; reordering positional args silently changes meaning.

---
Generated by SkillMake from https://gleam.run/documentation/ on 2026-07-02T18:41:46.923Z.
Verify against source before relying on details.

File: ~/.claude/skills/gleam/SKILL.md