Gleam Knowledge Patch

Gleam Knowledge Patch

Use this skill when writing, reviewing, upgrading, or packaging Gleam code. Start with the breaking-change checklist, then read the reference file that matches the work. Prefer the project's compiler, manifest, source, and tests when they disagree with general guidance.

Reference index

Breaking changes and deprecations

Use canonical configuration keys

Write snake-case keys in gleam.toml:

[dev_dependencies]
gleeunit = ">= 1.0.0 and < 2.0.0"

[repository]
tag_prefix = "my_package-v"

The older dev-dependencies and tag-prefix spellings still parse but are deprecated. JavaScript settings also use snake case, including source_maps and typescript_declarations.

Migrate retired standard-library APIs

• Use int.range, not removed list.range.
• Import decoders from gleam/dynamic/decode, not gleam/dynamic.
• Use list.flatten, not removed list.concat.
• Use drop_start, drop_end, pad_start, pad_end, trim_start, and trim_end, not the removed left/right names.
• Replace the removed queue, iterator, and regex modules with gleam_deque, gleam_yielder, and gleam_regexp.
• Use gleam/bytes_tree and gleam/string_tree instead of the removed builder modules.
• Replace result.then, result.unwrap_both, function.tap, int.digits, int.undigits, io.debug, and other retired helpers with the current APIs described in the standard-library reference.

Update deprecated language patterns

• Replace _ as value with value; the formatter performs this rewrite.
• Keep the returned value from immutable updates. Discarding a pure call now warns.
• Test list emptiness with patterns or items == [] / items != [], not a full list.length traversal.
• Do not depend on internal custom-type layouts from generated JavaScript. Use the supported constructor, predicate, and accessor exports.

Satisfy publishing gates

Before gleam publish:

• Replace the generated placeholder README and ensure a README exists.
• Remove modules that expose no public type or function.
• Keep package modules beneath the package namespace unless a deliberate exception is confirmed.
• Review confirmations for 0.* packages and names beginning with gleam_.
• Ensure Hex OAuth2, MFA for writes, and local token encryption can complete.
• Keep production modules and dependencies free of development-only imports.

Language quick reference

Assertions and debugging

Use Boolean assert when a false condition should panic with expression and operand details useful to test frameworks:

assert telecom.is_up(key, strict, 2025) as "internet must be available"

Add as "message" to let assert for a custom panic message. Prefix an expression with echo to print its value and source location to standard error without consuming the value; echo value as "message" adds context. Publishing warns about leftover echo expressions.

Constants

Constants support record updates, list prepending from another constant list, and incomplete todo values:

pub const dev = HttpConfig(..base, port: 4000)
pub const mammals = ["platypus", ..other_mammals]
pub const pending = Pokemon(number: 173, name: todo, hp: todo)

A constant containing todo can be type-checked and analysed, but the program cannot run.

Guards, pipelines, and records

String concatenation with <> is valid in case guards. Given value |> function(1, 2), Gleam first tries function(value, 1, 2) and, if that fails to type-check, tries function(1, 2)(value). Use a capture when the piped value belongs in another argument position.

Record updates can change a generic parameter:

pub fn replace(data: Named(a), replacement: b) -> Named(b) {
  Named(..data, value: replacement)
}

Direct field access on a multi-variant custom type is valid only when every possible variant has that field at the same position and with the same type, or after matching has narrowed the variant.

Patterns and bit arrays

Alternative case patterns must bind identical names with identical types and cannot be nested inside another pattern. The compiler diagnoses unreachable string-prefix clauses, redundant comparisons, impossible integer segments, truncating bit-array literals, and clauses covered by earlier bit-array patterns.

A bit-array integer segment defaults to 8 bits; a float segment defaults to 64 bits. size(n) uses the selected unit, whose default is one bit. Use :bits for any alignment and :bytes to require byte alignment. UTF segments accept endianness and pattern sizes may contain calculations.

Check the target-specific limits before relying on advanced bit arrays. JavaScript supports unaligned and dynamic segments, unit, 16-bit floats, UTF-16, and UTF-32, but integer patterns wider than 52 bits truncate and warn.

Build, dependency, and package workflow

Development and CI

Put development-only modules in dev/, define main in <package>_dev, and use:

gleam dev
gleam dev --no-print-progress

src/ can import only regular dependencies and other src/ modules. dev/ and test/ can import all dependency scopes and source directories.

Dependencies

Git dependencies require an explicit ref:

[dependencies]
gleam_stdlib = { git = "https://github.com/gleam-lang/stdlib.git", ref = "957b83b" }

Inspect resolution and updates with:

gleam deps tree
gleam deps tree --package package_c
gleam deps tree --invert package_b
gleam deps outdated

Do not combine --package and --invert. Resolution errors trace constraint chains, update commands identify changed versions and out-of-range major releases, and deps outdated always reports a summary count.

JavaScript output

[javascript]
runtime = "bun"
source_maps = true
typescript_declarations = true

The runtime may be node, deno, or bun; Node is the default. Serve .map files beside the generated JavaScript. Configure Deno permissions under [javascript.deno].

Erlang distribution

Use gleam export erlang-shipment for a relocatable directory with cross-platform launchers and forwarded POSIX signals. Use gleam export escript for one executable file that can run on a machine with Erlang installed.

FFI quick reference

External declarations

Give an external function a Gleam body when it needs a fallback on targets without the corresponding external implementation. External types accept target-specific definitions:

@external(erlang, "erlang", "map")
@external(javascript, "../dict.d.mts", "Dict")
pub type Dict(key, value)

JavaScript external paths are resolved relative to the declaring Gleam file. Bare package specifiers are accepted, but Gleam does not install the npm package. External source files may use .mjs, .cjs, .mts, .cts, .jsx, or .tsx.

Runtime representations

• On BEAM, String is a UTF-8 binary, Nil is nil, Result is {ok, Value} or {error, Value}, fieldless variants are snake-case atoms, variants with fields are tagged tuples, and Dict is a map.
• In JavaScript, Nil is undefined, tuples are immutable arrays, and both Gleam number types use JavaScript numbers while retaining Gleam's numeric constraints.
• Construct and inspect lists, results, bit arrays, and custom types through the generated prelude and module APIs. Use compiled gleam/dict functions for dictionaries.

Editor workflow

The language server analyses unsaved buffers for the project's configured target without generating code or compiling Erlang or Elixir, so analysis does not execute foreign code. Outside a Gleam project it only formats.

Use its actions to generate functions, variants, encoders, and decoders; create missing modules; exhaustively match values; add labels, parameters, and annotations; correct operators; rename symbols and modules; qualify imports; and extract constants, variables, functions, pipeline segments, or assignment values. Read the editor reference for the exact scope and edge cases of each action.