Gleam

JavaScript source maps

2026-04-24T00:00:00Z

Gleam is a type safe and scalable language for the Erlang virtual machine and JavaScript runtimes. Today Gleam v1.16.0 has been published, let's go over what's new.

Gleam gets source maps

Gleam's robust type system makes runtime errors very rare, but it would be naive to say that it's never necessary to debug Gleam code at runtime. When compiling code to JavaScript one challenge for runtime debugging is that the error and the source code shown is that of the compiled JavaScript, not the Gleam the programmer actually wrote.

The solution to this problem is source maps, additional files that Gleam's compiler can now generate, teaching browsers and JavaScript runtimes what the original code is and how it maps on to the JavaScript it runs. Here it is in action with Safari's dev-tools:

As you may know, it's not limited to just displaying the code, it also translates exception stack traces to the original locations, and enables use of breakpoints and debuggers.

To enable source maps set the javascript.source_maps property to true in your gleam.toml, and ensure that you are serving these new files to the web browser along with your JavaScript code. If you are serving the build directory or using Lustre's dev-tools then there's nothing else to do.

name = "my_project"
version = "1.0.0"

[javascript]
source_maps = true

[dependencies]
gleam_stdlib = ">= 1.0.0 and < 2.0.0"

A huge thank you to Ameen Radwan for this big improvement. Folks who enjoy breakpoint debugging will be especially pleased.

Package-level fault tolerance

Gleam is a fully-typed language, so to compile a module of Gleam code the compiler must first successfully compile all the modules it imports in order to have the required type information. Attempting to analyse modules without this information would result in a cascading failure of incorrect and misleading error messages, so when a module cannot be compiled the build tool stops and reports the errors.

This behaviour successfully prevents the error cascade, but it has been a source of confusion at times. Some developers may not realise they have an error upstream in their project and so do not understand why the language server is providing minimal assistance, presuming that it is broken.

Worse still, because compilation stops at the first failed module the language server may be unable to help with modules that do not directly or indirectly import an invalid module, but just happen to come after them in the compilation order. There's no justifiable reason why these modules could not have been compiled, but the developer is stuck without them.

These two pain points have now been resolved. If the programmer opens in their editor a module that genuinely could not be compiled, then the language server will display a diagnostic on the import that leads to the problem, removing the confusion.

When a module fails to compile the build tool will prune that sub-tree of modules and move on to the next set of modules that can be compiled, ensuring that the programmer has as much up-to-date information as possible available to them in their editor.

Thank you Giacomo Cavalieri! This will make a big difference to some Gleam programmers.

Faster string pattern matching

The compiler now emits more efficient code when matching on single-character string prefixes on the JavaScript target. For example, glance (a Gleam package that can parse Gleam code) is now nearly 30% faster on the JavaScript target:

# before:
min: 10.8ms, max: 365.82ms, median: 14.74ms, mean: 14.76ms
warmup: 100/1.5s, total post-warmup: 1000/14.76s

# after:
min: 8.96ms, max: 143.76ms, median: 10.72ms, mean: 11.06ms
warmup: 100/1.24s, total post-warmup: 1000/11.06s

Thank you Rebecca Reusch and Surya Rose!

Record update fault tolerance

To provide a good language server experience with invalid code, Gleam's compilation aims to be fault-tolerant, and will attempt to continue analysing the code after finding an error.

With this release the analysis of record update expressions is now fault- tolerant, and the compiler now shows a better error message when trying to use the record update syntax with variants that have no labelled fields.

Thank you Giacomo Cavalieri!

Oversized int pattern warning

The largest size an int can have on JavaScript is 52 bits, after which precision is lost. The compiler now raises a warning on the JavaScript target when a pattern attempts to extract an int larger than JavaScript supports, to avoid unexpected results.

warning: Truncated bit array segment
  ┌─ /src/app/warning.gleam:3:20
  │
3 │     let <<_, number:152>> = sha
  │                     ^^^

This segment is a 152-bit long int, but on the JavaScript target
numbers have at most 52 bits. It would be truncated to its first 52 bits.
Hint: Did you mean to use the `bytes` segment option?

Thank you Giacomo Cavalieri!

Spoiling practical jokes

The compiler now emits a helpful error message when source code contains an invalid unicode character that looks similar to a correct character.

error: Syntax error
  ┌─ /src/parse/error.gleam:1:20
  │
1 │ pub fn main() { #(1‚ 2) }
  │                    ^ Unexpected character

This looks like ascii comma, but it is actually the unicode low single
comma quotation mark.

Bad news for mischievous pranksters, good news for folks who don't like debugging unexpected parse errors.

Hex package ownership management

Niklas Kirschall has added the new gleam hex owner add command, allowing folks to add additional owners to their Hex packages. Thank you Niklas!

Hex package manager error message improvements

The build tool now produces a nicer error message when trying to add a package version that doesn't exist. For example, running gleam add wisp@11 will now produce:

error: Dependency resolution failed

The package `wisp` has no versions in the range >= 11.0.0 and < 12.0.0.

Thank you Giacomo Cavalieri!

David Matz has also updated our error handling for the new error types recently added to Hex's API, fixing some incorrect and misleading messages that we would show due to attempting to parse them as the old errors. Thank you David!

Add and remove anonymous function code actions

Gleam is a functional programming language, so functions are very commonly used as values, and are passed as arguments to other functions. Sometimes an anonymous function is used.

let add_item = fn(item) { catalog.record(item) }

Other times the function is referenced directly.

let add_item = catalog.record

These two expressions are equivalent, and the programmer would pick between the two depending on what they find to be clearer at each point in their code.

To make writing Gleam even nicer the language server now offers code actions to switch between the two syntaxes. For example:

pub fn main() {
  [-1, -2, -3] |> list.map(fn(a) { int.absolute_value(a) })
                        // ^^ Activating the "Remove anonymous function"
                        // code action here
}

Would result in this code:

pub fn main() {
  [-1, -2, -3] |> list.map(int.absolute_value)
}

And with this code the other action could be used to reverse the change.

Thank you Eli Treuherz!

Extract function code action improvements

Gleam's language server has an "extract function" code action that can be used to… well… extract a function.

It can now be used in pipelines to extract a part of one into a function. For example, triggering it here:

pub fn words(phrase: String) -> List(String) {
  phrase
  |> string.lowercase
  // ^^^
  |> string.replace(each: "jak", with: "lucy")
  // ^^^ selecting these two steps of the pipeline
  |> string.split(on: " ")
}

Would result in the following code:

pub fn words(phrase: String) -> List(String) {
  phrase
  |> function
  |> string.split(on: " ")
}

fn function(string: String) -> String {
  string
  |> string.lowercase
  |> string.replace(each: "jak", with: "lucy")
}

It has also been improved to work better with assignments, extracting the assigned value. For example:

pub fn personal_blog() {
  let introduction =
    html.main([], [
      html.h1([], [html.text("Hello, world!")]),
      html.p([], [html.text("Gleam is cool")])
    ])
  //^^^ Triggering "extract function" on this expression

  html.body([introduction, blog_posts()])
}

Would result in the following code:

pub fn personal_blog() {
  let introduction = function()
  html.body([introduction, blog_posts()])
}

pub fn function() {
  html.main([], [
    html.h1([], [html.text("Hello, world!")]),
    html.p([], [html.text("Gleam is cool")])
  ])
}

Thank you Giacomo Cavalieri!

Replace `_` with type code action

Gleam's type hole syntax allows to omit parts of a type annotation, putting no restrictions on what that part of the type can be inferred as. This can be convenient when sketching out new code, but it's best practice to have full annotations to make the code and the intended behaviour of the code easier to understand.

To aid with moving to full annotation the language server has a code action to replace a type hole with the underlying type. For example:

pub fn load_user(id: Int) -> Result(_, Error) {
  sql.find_by_id(id)
  |> result.map_error(CannotLoadUser)
}

Triggering the code action over the _ will result in the following code:

pub fn load_user(id: Int) -> Result(User, Error) {
  sql.find_by_id(id)
  |> result.map_error(CannotLoadUser)
}

Thank you Giacomo Cavalieri!

Constant list prepending

The compiler now supports list prepending in constants. For example:

pub const viviparous_mammals = ["dog", "cat", "human"]

pub const all_mammals = ["platypus", "echidna", ..viviparous_mammals]

Thank you Surya Rose!

Language server completion improvements

The language server's completion capability has been improved to understand Gleam code more precisely. It now shows completions for the labelled argument of a record when writing a record update, and no longer shows completions for values when editing a qualified type.

Thank you Giacomo Cavalieri!

Tuple formatting improvement

Gleam has a source code formatter, automating the business of formatting your code, so you can focus on your task, and not get stuck in another argument about whether or not you should use a trailing comma.

With this release the formatting of long nested tuples has been improved. Previously the formatter would split only the last tuple, but now it favours first splitting each element onto its own line:

// Old format
#(#(12345, wobble), #(
  some_long_tuple,
  "passed_as_last_argument"
))

// New format:
#(
  #(12345, wobble),
  #(some_long_tuple, "passed_as_last_argument")
)

Thank you to formatter wizard Giacomo Cavalieri!

More external code source extension support

Gleam's external type and external function features allow Gleam code to make use of code written in other languages on the same runtime, and Gleam's build tool will process source files of these languages that are included in a source directory of a Gleam project.

Some JavaScript runtimes now have built-in support for TypeScript and JSX, so the build tool has had support for including files with mts, cts, jsx, and tsx extensions.

Thank you Niklas Kirschall!

And the rest

And thank you to the bug fixers and experience polishers: Andrey Kozhev, Daniele Scaratti, Eyup Can Akman, Giacomo Cavalieri, Giovanni Maria Zanchetta, John Downey, Louis Pilfold, Lucy McPhail, Luka Ivanović, Niklas Kirschall, and Surya Rose.

For full details of the many fixes and improvements they've implemented see the changelog.

A call for support

Gleam is not owned by a corporation; instead it is entirely supported by sponsors, most of which contribute between $5 and $20 USD per month, and Gleam is my sole source of income.

We have made great progress towards our goal of being able to appropriately pay the core team members, but we still have further to go. Please consider supporting the project or core team members Giacomo Cavalieri and Surya Rose on GitHub Sponsors.

Thank you to all our sponsors! And special thanks to our top sponsor:

Try Gleam

Upgrading Hex security

2026-03-16T00:00:00Z

Gleam is a type safe and scalable language for the Erlang virtual machine and JavaScript runtimes. Today Gleam v1.15.0 has been published, let's go over what's new.

The Hex package manager

Gleam is a BEAM language, so it uses Hex, the package manager of the Erlang ecosystem. Hex recently introduced a new OAuth2 based authentication system, replacing the old system of exchanging the account's username and password for a long-lived token. This new system has many security advantages:

Multi-factor authentication is used for all endpoints that require write permissions, so stolen credentials or tokens are insufficient to perform sensitive actions.
Hex clients such as Gleam never see your password, so there is less opportunity for an attacker to harvest credentials given access to your workstation.
The access tokens are short lived, so if stolen there is only a small window in which they could be used by the attacker.
The Hex site can integrate with other OAuth providers, enabling companies to use their existing identity management and audit systems to secure Hex.

Gleam now uses exclusively this new system for authentication, and any existing legacy tokens that Gleam has stored locally will be revoked the first time that the new version of Gleam is used with Hex. The legacy system will be disabled for Gleam packages in future.

Lastly, the password used for encrypting local Hex tokens must now be at least 8 characters in length.

This work was done in collaboration with The Erlang Ecosystem Foundation. A huge thank-you to Jonatan Männchen and the rest of the team there! If you would like to support important infrastructure projects for the whole ecosystem consider becoming a member of the foundation.

Better Hex errors

It's possible for Hex operations to fail, for example, attempting to depend on a package that does not exist, or attempting to publish a new version of a package that you are not the maintainer of. When this happens we typically show the programmer the error message as-is from the Hex API. These error messages are not bad, but compared to the other error messages from Gleam it can be not immediately obvious what the problem is and how the programmer should proceed.

Ameen Radwan and vyacheslavhere have added custom errors for these two scenarios, fixing the two main stumbling points folks have with Hex errors. Thank you both!

Guard clause ergonomics

Adi Salimgereyev has implemented two nice improvements to guard expressions in case expressions. Firstly, the string concatenation operator can now be used:

case message {
  action if version <> ":" <> action == "v1:delete" -> handle_delete()
  _ -> ignore_command()
}

And a helpful custom error message is now shown when int and float binary operators are used incorrectly in case expression guards.

Thank you Adi Salimgereyev!

Additionally, the language server now supports renaming, go to definition, hover, and finding references from expressions in case clause guards. Thank you Surya Rose!

Internal types presentation

Gleam's internal publicity level allows definitions to be technically importable and usable from other modules, but not be part of the actual public API of the module. This may be useful for creating "escape hatch" APIs, or for facilitating shared functionality between modules owned by the same maintainer.

Because they are not public, these internal definitions are not shown in the generated API documentation, and are not suggested for autocompletion by the language server. There was however some compiler and language server functionality where they did not get special treatment, which could make it not immediately obvious that a definition is internal. Giacomo Cavalieri has fixed these now!

The "Add missing patterns" code action will insert a catch all pattern for internal types, the language server will no longer show completions for the fields of internal types, and the compiler no longer shows the structure of internal types when displaying an "Inexhaustive patterns" error. Thank you Jak!

JavaScript FFI additions

Gleam can compile to JavaScript, making use of the wealth of code that exists in the JavaScript ecosystem. To enable JavaScript code to construct and work with Gleam data structures the compiler provides an API for each type in a Gleam codebase. This release brings some improvements to this API:

The BitArray$isBitArray and BitArray$BitArray$data functions have been added, enabling JavaScript to consume the Gleam prelude bit-array type.

import { BitArray$isBitArray, BitArray$BitArray$data } from "../gleam.mjs";

export function writeFile(path, data) {
  if (BitArray$isBitArray(data)) {
    const buffer = BitArray$BitArray$data(data);
    return fs.write(path, buffer);
  }
}

TypeScript types are also generated for this API. Functions such as BitArray$isBitArray that check if a value is of a given type now have the return type value is TypeName, so the TypeScript type checker can use these functions to understand whether or not the value is the expected Gleam type.

Package quality publish checks

We want the Hex package repository to be full of high-quality and production-ready code. It is not a place for sharing or showing-off prototypes, and name-squatting is against the terms of service. We keep an eye on the packages that are published over time, monitoring for any undesirable trends that we wish to discourage, and introducing checks to prevent them occasionally.

One problem we noticed recently was folks opting to not document their package with a README, which is intended to serve as the home-page of the documentation. - The build tool will now refuse to publish any package that has the default README generated by the gleam new command, or is missing any README altogether.

Thank you Giacomo Cavalieri!

Code folding

The language server now supports textDocument/foldingRange, enabling folding for contiguous import blocks and multi-line top-level definitions, such as function bodies, custom types, constants, and type aliases.

import gleam/int
import gleam/list
import gleam/string

This block of imports can now be folded in the editor like so:

import gleam/int ...

Thank you Aayush Tripathi!

CLI documentation improvements

The help command and --help flag can be used with Gleam's command line interface to view a concise overview of various commands. This was helpful for the very basics, but typically the programmer would need to refer to the documentation on the Gleam website for more complex tasks, such as adding a dependency from git, or adding a package with a specific version constraint.

Stopping what you are doing to go and find a web page is annoying, so the gleam help add, gleam help deps, and gleam help docs commands have been improved with much more detailed documentation output, covering these sorts of tasks.

Consistent configuration

Gleam tooling uses the gleam.toml file for configuration. Due to a mistake very early in Gleam's initial development there has been an odd inconsistency with the names of two of the keys in this file: dev-dependencies and tag-prefix. They use sausage-case, but all the others use snake_case!

With this release they are now canonically snake case, making them consistent. The old format continues to be supported, but it is deprecated.

name = "my_app"
version = "2.4.0"

[dependencies]
gleam_stdlib = ">= 0.44.0 and < 2.0.0"

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

Extract anonymous function

The Extract function code action now has a special-case for extracting anonymous functions, using the body of the anonymous function as the body of the new extracted function.

pub fn double(numbers: List(Int)) -> List(Int) {
  let multiplier = 2
  list.map(numbers, fn(number) { number * multiplier })
  //                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
}

When this anonymous function is extracted the code is refactored like so:

pub fn double(numbers: List(Int)) -> List(Int) {
  let multiplier = 2
  list.map(numbers, function(_, multiplier))
}

fn function(number: Int, multiplier: Int) -> Int {
  number * multiplier
}

Thank you Hari Mohan!

Module usage renaming

The rename action can be triggered on usages of a module, rather than just its import, for example:

import lustre/element
import lustre/element/html
import lustre/event

fn view(model: Int) -> element.Element(Msg) {
  //                     ^  Renaming module to `el` here
  let count = int.to_string(model)

  html.div([], [
    html.button([event.on_click(Incr)], [element.text(" + ")]),
    html.p([], [element.text(count)]),
    html.button([event.on_click(Decr)], [element.text(" - ")]),
  ])
}

Using renaming when hovering on module name would result in the following code:

import lustre/element as el
import lustre/element/html
import lustre/event

fn view(model: Int) -> el.Element(Msg) {
  let count = int.to_string(model)

  html.div([], [
    html.button([event.on_click(Incr)], [el.text(" + ")]),
    html.p([], [el.text(count)]),
    html.button([event.on_click(Decr)], [el.text(" - ")]),
  ])
}

Thank you Vladislav Shakitskiy!

Add missing type parameter code action

The language server now suggests a quick-fix code action for when a custom type definition uses a type parameter in its variants that have not been declared in its header.

pub type Store {
  Store(name: String, data: inner_type)
}

This code doesn't compile as the inner_type type variable hasn't been declared. Running the code action results in the code being fixed like so:

pub type Store(inner_type) {
  Store(name: String, data: inner_type)
}

Thank you Andi Pabst!

String prefix language server triggering

It's now possible to find references and rename variables in string prefix patterns:

case wibble {
  "1" as digit <> rest -> digit <> rest
  //     ^^^^^    ^^^^
  // You can now trigger "Find references" and "Rename" from here
}

Thank you Igor Castejón!

More precise completions

The language server protocol has some ambiguities in places, which means that different editors can have slightly different behaviour for the same actions. One way in which this has caused a problem for Gleam programmers is when using a completion where the suffix already exists in the code. For example, imagine you're updating your code to fully qualify the uses of the Json type:

pub fn payload() -> js|Json
//                    ^ typing the module name

Accepting the json.Json completion in some editors would result in the incorrect code json.JsonJson. To prevent this annoyance the language server now gives more precise instructions to the editor, so all will render the correct json.Json code.

Thank you Giacomo Cavalieri!

Signature help type parameter names

The language server now shows the original names used for type parameters in the signature help information. This can help understand what each of the parameters mean. For example:

pub fn twice(data: input, function: fn(input) -> output) -> output {
  function(function(data))
}

pub fn main() {
  twice( )
  //    ↑ Cursor here
}

This will show this signature help information:

twice(input, fn(input) -> output)

Thank you Samuel Cristobal!

Other language server improvements

Developer experience and productivity are our main focus, so we have lots of small but impactful quality-of-life improvements in the language server.

The language server now suggests completions for keywords that are expressions, like echo, panic, and todo. Thank you Giacomo Cavalieri.

The "Fill labels" code action now uses variables from scope when they match the label name and expected type, instead of leaving a todo placeholder that the programmer would need to replace with those variables. Thank you Vladislav Shakitskiy.

The "Interpolate String" code action now lets the user "cut out" any portion of a string, regardless of whether it is a valid Gleam identifier or not. Thank you Hari Mohan.

The language server now performs best-effort zero value generation for decode.failure and has support for Nil when using the generate dynamic decoder code action. Thank you Hari Mohan.

The language server now allows extracting the start of a pipeline into a variable. Thank you Giacomo Cavalieri.

Custom type definitions and custom type variants now show their documentation on hover, so you can see what it looks like when rendered. Thank you Giacomo Cavalieri.

And the rest

And thank you to the bug fixers and experience polishers: acandoo, Andrey Kozhev, Christian Widlund, daniellionel01, Etienne Boutet, Gavin Morrow, Giacomo Cavalieri, Hari Mohan, John Downey, Justin Lubin, Surya Rose, vyacheslavhere, and Vladislav Shakitskiy.

For full details of the many fixes and improvements they've implemented see the changelog.

A call for support

Gleam is not owned by a corporation; instead it is entirely supported by sponsors, most of which contribute between $5 and $20 USD per month, and Gleam is my sole source of income.

Thank you to all our sponsors! And special thanks to our top sponsors:

Try Gleam

Join us at Gleam Gathering

2026-02-11T00:00:00Z

Gleam Gathering is right around the corner! On the 21st of February the Gleam team and many friendly Gleamlins will be meeting in Bristol UK for the first ever 100% Gleam conference. This is a milestone for the community, and we are very excited. There will be talks from community members and Gleam core team members on topics ranging from compiler optimisation to trains (seemingly a popular subject within the Gleam community).

Around the presentations there's opportunity to meet and talk with folks from the community, and afterwards we will be going to a retro-games arcade for some fun. I may check out the local rock-climbing gym the day after too!

If you'd like to join us then there's a few last minute tickets remaining. See you in Bristol!

The happy holidays release 2025 🎁

2025-12-25T00:00:00Z

Merry Christmas and happy holidays everyone! Gleam is a type-safe and scalable language for the Erlang virtual machine and JavaScript runtimes. Gleam v1.14.0 is our Xmas gift for you, let's unwrap it and take a look inside.

External annotations for external types

Gleam doesn't exist in a vacuum, instead builds upon the existing Erlang and JavaScript ecosystems. It's not uncommon for Gleam programs and libraries to internally make use of code written in other languages in the same ecosystem, and Gleam code can be called from those languages too. To help with the interoperability between these languages the Gleam compiler can generate Erlang type specifications and TypeScript declaration files. These can be used with external type checkers and static analysis tooling to ensure the various languages are calling each other's code correctly.

// Function written in Gleam
pub fn greet(name: String) -> String {
  "Hello, " <> name <> "!"
}

% Generated Erlang type spec
-spec greet(binary()) -> binary().

// Generated TypeScript type definition
export function greet(name: string): string;

When writing bindings to code in other languages, Gleam's external type feature is used to declare a type that can be referenced in Gleam, but since it originates from outside of Gleam it has an unknown shape and cannot be constructed directly. A very useful feature for designing Gleam-y APIs for external code! The limitation here was that due to Gleam not knowing anything about these external types, it was not able to produce a precise definition in generated Erlang or TypeScript type definitions, having to fall back to the correct but vague "any" type of each language.

The @external annotation is now supported for external types, giving the programmer a way to specify an Erlang or TypeScript type definition to be used. For example, the Dict type from the standard library can now be written as the following:

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

% Generated Erlang type definition
-type dict(K, V) -> erlang:map(K, V).

// Generated TypeScript type definition
import type { Dict } from "../dict.d.mts";
export type Dict$<K, V> = Dict<K, V>;

Thank you Surya Rose and Yoshie for this!

Interference-based pruning for ints

Gleam uses pattern matching for flow control, a common feature of functional languages. This is where the programmer declares a series of patterns in a case expression, and the first clause has a pattern that matches the shape of the data being matched upon will be executed. Because these patterns are declarative the compiler can generate more optimised code than it would be able to for an if-else chain of boolean checks.

The previous release introduced interference-based pruning, a sophisticated optimisation that improves performance and detects more redundant patterns when pattern matching on binary data. This release extends this optimisation to work with int segments too, further increasing its effectiveness!

case bits {
  <<"a">> -> 0
  <<97>> -> 1
  // ^- This clause is unreachable because it's equal to "a".

  <<0b1:1, _:1>> -> 2
  <<0b11:2>> -> 3
  // ^- This clause is unreachable because of the previous

  _ -> 99
}

Thank you fruno!

Number normalisation in pattern matching analysis

Numbers can be written in several different formats in Gleam. Most the time they are written in decimal, but they could also be written in octal, hexadecimal, or binary, or scientific notation could be used for floats.

Gleam's compiler now internally normalises these values to a single canonical representation. This new representation is now used by the pattern matching analysis engine, further enabling optimisations such as interference-based pruning, making Gleam code faster and detecting more redundant clauses.

Thank you ptdewey!

More precise incorrect subject count error message

Gleam's case expression can be used to match on multiple values at the same time. If two values are being matched on, then each clause will need two patterns. If three are matched on then three patterns are needed. Etc. Providing the wrong number of patterns will result in a compile error, and now the error has been improved to show exactly where the problem is.

case wibble {
  0, _ -> 1
  ^^^^ Expected 1 pattern, got 2
  0 |  -> 1
    ^ I was expecting a pattern after this
}

Thank you fruno!

Fault tolerance

Gleam's compiler implements fault tolerant analysis. This means that when there is some error in the code the compiler can still continue to analyse the code to the best of its ability, ignoring the invalid parts. Because of this, the Gleam language server can have a good understanding of the code and provide IDE features even when the codebase is in an invalid state.

Giacomo Cavalieri made type analysis of constants fault tolerant. Adi Salimgereyev made the field definitions of custom type variants fault tolerant. mxtthias made bool pattern matching syntax errors fault tolerant.

Thank you all!

Faster equality testing

The performance of == and != has been improved for fieldless custom type variants when compiling to JavaScript. This was done by generating comparison code specific to the custom type rather than using the generic equality check code. Thank you Nafi for this improvement!

Redundant module warnings

A Gleam module with no public types or functions can't do anything, so it's not useful! The compiler now emits a warning when a module contains no public definitions. The gleam publish command will also return an error for packages with modules like these, prompting the programmer to remove the module.

Thanks to Vitor Souza!

Detached documentation warnings

Gleam has /// comments for writing documentation, with the comment being placed immediately above the definition being documented. This syntax is visually similar to the regular // comment, so occasionally a Gleam programmer will accidentally place regular comments within documentation, causing the first part of the documentation to be "detatched", and not show up in the rendered HTML documentation for that code.

/// This documentation is not attached.
///
// This is regular comment.
///
/// This is the attached documentation.
pub fn wibble() {
  todo
}

The compiler now emits a warning when a documentation comment is not attached to a definition due to a regular comment in between, helping to prevent this mistake. Thank you Surya Rose!

Record update syntax for constants

Gleam's record update syntax can now be used in constant definitions, enabling constant records to be constructed from other constant records.

pub const base_http_config = HttpConfig(
  host: "0.0.0.0",
  port: 8080,
  use_tls: False,
  log_level: Info,
)

pub const dev_http_config = HttpConfig(
  ..base_http_config,
  port: 4000,
  log_level: Debug,
)

pub const prod_http_config = HttpConfig(
  ..base_http_config,
  port: 80,
  use_tls: True,
  log_level: Warn,
)

Thank you Adi Salimgereyev!

Latest Elixir support

Gleam's build tool can compile Gleam code, but also Erlang and Elixir code as well. This is part of Gleam's commitment to being part of the wider BEAM ecosystem, rather than an independent language that happens to use the same virtual machine. Practically, this means that Gleam programs can add Erlang and Elixir code or packages as dependencies, and not have to do additional work or configuration to use that code.

This release updates to the latest Elixir compiler API, fixing some warnings that would be emitted with previous versions of Gleam and the latest version of Elixir. Thank you Andrey Kozhev!

Outdated dependencies view

It is important to take great care when using dependency packages: They can save a lot of time, but all code added to a project has a maintenance cost and security considerations.

To help with this task we have been providing more tools for working with dependencies, the latest of which is the gleam deps outdated command. This command makes it much easier to identify which packages have available updates in the package repository.

$ gleam deps outdated
Package  Current  Latest
-------  -------  ------
wibble   1.4.0    1.4.1
wobble   1.0.1    2.3.0

Thank you Vladislav Shakitskiy!

Helpful git-not-installed error message

Dependency packages can be added from Git repositories as well as from the Hex package repository. The git program must be installed to use Git dependencies, and previously if it was not the build tool would fail with a not-very-helpful error message when trying to download these dependencies.

With this version the error message has been improved, and includes a link to instructions on how to install it.

error: Program not found

The program `git` was not found. Is it installed?

Documentation for installing Git can be viewed here:
https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

Thank you Andrey Kozhev!

Further code action support

The gleam binary also includes the Gleam language server, bringing IDE-like functionality to all editors that support the language server protocol. Several of the existing code actions (automated refactorings, etc) have been improved so they can be triggered from more places, or so they support a wider range of code.

The "inline variable" code action can now trigger when used over the let keyword of a variable to inline, rather than just the variable name and the usage of that variable.

The "add omitted labels" code action can now be used in function calls where some of the labels have been provided already. This greatly increases how often this code action is usable, a very impactful improvement!

The "generate function" code action can now trigger when used over constant values, while previously it could only be used in expressions within module functions. Gleam's type information analysis is used to contextually identify when a referenced name is a function, and so when this code action is relevant.

Thank you Giacomo Cavalieri for these!

Qualify and unqualify code actions can now be triggered on constants, instead of only on expressions within module functions. Thank you Vladislav Shakitskiy!

Type directed autocompletion

The Gleam language server provides autocompletion, sending a list of options for the programmer to select from. The options are ordered based upon how likely the programmer is to select each option, with the most likely candidates being presented first. This ordering now takes type information into account, with values that produce the correct type being ranked higher.

Thank you Surya Rose!

Missing patterns order improvement

Gleam performs exhaustiveness checking of case expressions, reporting an error if the patterns do not cover all the possible shapes of the data being matched upon.

error: Inexhaustive patterns
   ┌─ /Users/louis/Desktop/app/src/app.gleam:10:3
   │
10 │ ╭   case person {
11 │ │     Student(name:) -> name
12 │ │   }
   │ ╰───^

This case expression does not have a pattern for all possible values. If it
is run on one of the values without a pattern then it will crash.

The missing patterns are:

    Teacher(title:, name:)
    Visitor(name:)

The missing patterns in error messages and in the code generated by the "add missing patterns" code action used to be ordered lexicographically, but now they will be presented in definition order. This is more commonly the order that the programmer wants, so they are less likely to need to re-order them in their code.

Thank you fruno!

Merge case branches code action

There is a new code action which can merge case clauses that have the same body. For example:

case user {
  Admin(name:, ..) -> todo
//^^^^^^^^^^^^^^^^^^^^^^^^
  Guest(name:, ..) -> todo
//^^^^^^^^^^^^^^^^ Selecting these two branches you can
//                 trigger the "Merge case branches" code action
  _ -> todo
}

Triggering the code action would result in the following code:

case user {
  Admin(name:, ..) | Guest(name:, ..) -> todo
  _ -> todo
}

Little automated refactoring like these can make a big difference to the experience of writing and editing Gleam code. Thank you Giacomo Cavalieri!

Improved name selection in code actions

Another useful code action found in the language server is "generate function". It is available when the code is calling an unknown function, and it will generate the skeleton of a function with the correct name, arguments, and types.

To name the argument the language server looks at how it is called, reusing the name of any variables used, or the names of the types if the arguments given are not variables. This name selection has been improved, and will also look at the names of field labels when arguments are provided using the record access syntax.

pub type User {
  User(id: Int, name: String)
}

pub fn go(user: User) -> Session {
  authenticate(user.id, user.name)
}

Having the language server generate the missing authenticate function will produce the following code:

pub fn authenticate(id: Int, name: String) -> Session {
  todo
}

A similar improvement has been made for the "pattern match on variable" code action when used on tuples. Thank you Giacomo Cavalieri!

Language server rename failure notification

The Gleam language server supports the popular and extremely useful "rename" action. Previously if you attempted to rename something to that would result in a syntax error (e.g. putting a space in a function name) it would not perform the renaming, but it wouldn't tell you why. With this release it will now send a notification for the editor to display, letting the programmer know that it is an invalid name.

Thank you Giacomo Cavalieri!

Improved language server diagnostic grouping

The language server protocol (LSP) is a common interface that lets IDE engines (such as Gleam's language server) work with many different code editors. It's brilliant in what it enables, but unfortunately the specification is vague in some places, so different code editors interpret messages from the server in different ways. This occasionally results in some editors having not-quite providing the experience we intended when editing Gleam.

Recently we discovered that when we emit warnings or errors that point to multiple places in the source code the Zed editor would treat the two locations as independent, so the programmer would need to trigger "go to next diagnostic" to go to the next error. We have now adjusted the design of our diagnostics, bringing Zed inline with the behaviour of the other major editors.

Thank you fruno. Zedlings rejoice!

To be clear, we do not think that Zed was doing anything incorrect here. We love Zed! From our understanding both behaviours are correct due to ambiguity in the LSP specification.

Annotate all top level definitions code action

Gleam has total and perfect type analysis, so it can tell the type of every expression in a project, assuming there are no errors in the code that cause it to fail to compile. Type annotations are optional, and while they don't help the type analysis or make code "more typed", it is considered good style to annotate all module functions to help humans read the code.

The language server has for some time offered a code action for adding missing annotations to a single definition, and now it has another for doing all definitions at once.

pub const answer = 42

pub fn add(x, y) {
  x + y
}

pub fn add_one(thing) {
  let result = add(thing, 1)
  result
}

Triggering the "Annotate all top level definitions" code action on the name of function add_one results in the following code:

pub const answer: Int = 42

pub fn add(x: Int, y: Int) -> Int {
  x + y
}

pub fn add_one(thing: Int) -> Int {
  let result = add(thing, 1)
  result
}

This will be useful for folks who like to forego writing type annotations when quickly writing new code, or exploring a new design. Thank you Andrey Kozhev!

Command line API improvements

Various ergonomic improvements have been made to the command line interface of Gleam's build tool.

The help text displayed by gleam dev --help, gleam test --help, and gleam run --help has been improved: now each one states which function it's going to run. Thanks to Giacomo Cavalieri.

The --invert and --package options of gleam deps tree are now mutually exclusive; if both options are given the command will fail. Previously, --invert would be silently ignored if given together with --package. Thanks to Evan Silberman.

The format used for gleam deps list and the notice of available major version upgrades has been improved.

And the rest

And thank you to the bug fixers and experience polishers:

Adi Salimgereyev, Elias Haider, fruno, Giacomo Cavalieri, Gurvir Singh, Ioan Clarke, Louis Pilfold, Matias Carlander, Patrick Dewey, Richard Viney, and Surya Rose.

For full details of the many fixes and improvements they've implemented see the changelog.

A call for support

Gleam is not owned by a corporation; instead it is entirely supported by sponsors, most of which contribute between $5 and $20 USD per month, and Gleam is my sole source of income.

We have made great progress towards our goal of being able to appropriately pay the core team members, but we still have further to go. Please consider supporting the project however you can.

Thank you to all our sponsors! And special thanks to our top sponsors:

Try Gleam

Formalising external APIs

2025-10-19T00:00:00Z

Gleam is a type-safe and scalable language for the Erlang virtual machine and JavaScript runtimes. Today Gleam v1.13.0 has been published. Let's go over all the highlights now.

External API for Gleam data

One of Gleam's strengths is that it is part of the BEAM and JavaScript ecosystems, enabling Gleam programs to take advantage of code written in Erlang, Elixir, JavaScript, and more. This is a large part of how Gleam was able to become a practical production-ready language so quickly, by not restricting Gleam programmers to just the comparatively young Gleam package ecosystem.

A function written in one of these other languages can be imported into a Gleam module as an "external function", and then called without any additional performance overhead.

@external(erlang, "moon_base", "launch_spaceship")
pub fn lift_off(countdown: Int) -> Result(Spaceship, LaunchError)

Here the Erlang function launch_spaceship from the module moon_base is being imported.

One restriction to external functions is that they will need to return data types that Gleam can understand. Gleam's "external type" feature lets the programmer refer to types defined in other languages, but if the programmer wants to be able to directly construct and pattern match data from external functions it will need to be in a format compatible with Gleam data types.

Often a programmer will write a small wrapper function in the external language to convert the data, and also to make the interface adhere to Gleam patterns and conventions.

-module(moon_base).
-export([launch_spaceship/1]).

launch_spaceship(Countdown) ->
    try
        Spaceship = launch_control:launch_spaceship(Countdown),
        {ok, Spaceship}
    catch
        error:no_fuel -> {error, no_fuel};
        error:bad_weather -> {error, bad_weather}
    end.

This launch_spaceship Erlang function wraps the function from the launch_control module, converting the exception-based API into a Result type, the Erlang representation of Gleam's Ok and Error variants.

One thing that a Gleam programmer may find challenging is knowing how to construct Gleam data in these wrapper functions. A lack of detailed documentation made it unclear what the correct approach should be.

This lack of clarity makes learning how to use external code more challenging, and worse, it may result in programmers using internal APIs that are intended only to be used by the compiled Gleam code. If the Gleam ecosystem were to grow with many packages using these internal APIs, it would force the Gleam core team to support them as if they were public APIs. Committing to these APIs would greatly limit what changes we can make to the internal representation of Gleam data, and make many potential performance improvements impossible.

To fix this we have done two things. First, we have created a guide on Gleam externals, detailing how to correctly write and use externals.

Secondly, a dedicated API is now provided for JavaScript-based code to work with Gleam data, both making usage clearer and giving the Gleam core team maximum freedom to improve performance in future. Each data type defined in Gleam will have a set of functions defined to work with it, for example:

// In src/person.gleam
pub type Person {
  Teacher(name: String, subject: String)
  Student(name: String)
}

// In src/my_javascript_code.mjs
import {...} from "./person.mjs";

// Constructing custom types
let teacher = Person$Teacher("Joe Armstrong", "Computer Science");
let student = Person$Student("Louis Pilfold");

let randomPerson = Math.random() > 0.5 ? teacher : student;

// Checking variants
let randomIsTeacher = Person$isTeacher(randomPerson);

// Getting fields
let teacherSubject = Person$Teacher$subject(teacher);

// The `name` field is shared so can be accessed from either variant
let personName = Person$name(randomPerson);

There will be a migration period where existing JavaScript externals will need to migrate over to the new API. We have created tooling to analyse the Gleam package ecosystem to identify code that is in need of updating, and we will be helping with this process.

Further additions will be made to the externals guide detailing useful patterns, how to avoid common problems, and advising when and how to use externals.

Thank you Surya Rose for taking the lead role in implementing these new APIs, and for the Gleam team more widely for the design of this addition!

Improved bit array exhaustiveness checking

Gleam's bit array syntax allows you to declaratively construct and parse binary data in a way that may be easier to understand than using binary operators.

The compiler now applies an optimisation known as "interference based pruning" when compiling bit array pattern matching where matches are performed at the start of bit arrays. This optimisation drastically reduces compile times, memory usage and the compiled code size, removing many redundant checks.

It is particularly impactful for programs that pattern match on some fixed patterns at the start of the bit array. For example, network protocol parsers.

pub fn parse_headers(headers: BitArray, bytes: Int) -> Headers {
  case headers {
    <<"CONTENT_LENGTH" as header, 0, value:size(bytes), 0, rest:bytes>>
    | <<"QUERY_STRING" as header, 0, value:size(bytes), 0, rest:bytes>>
    | <<"REQUEST_URI" as header, 0, value:size(bytes), 0, rest:bytes>>
    // ...
    | <<"REDIRECT_STATUS" as header, 0, value:size(bytes), 0, rest:bytes>>
    | <<"SCRIPT_NAME" as header, 0, value:size(bytes), 0, rest:bytes>>
      -> [#(header, value), ..parse_headers(rest)]
  }
}

Additionally, the compiler now raises a warning for unreachable branches that are matching on bit array segments that could never match. Consider this example:

pub fn get_payload(packet: BitArray) -> Result(BitArray, Nil) {
  case packet {
    <<200, payload:bytes>> -> Ok(payload)
    <<404, _:bits>> -> Error(Nil)
    _ -> Ok(packet)
  }
}

There's a subtle bug here. The second branch can never match since it's impossible for the first byte of the bit array to have the value 404. The new error explains this nicely:

warning: Unreachable pattern
  ┌─ /src.gleam:4:5
  │
4 │     <<404, _:bits>> -> Error(Nil)
  │     ^^^^^^^^^^^^^^^
  │       │
  │       A 1 byte unsigned integer will never match this value

This pattern cannot be reached as it contains segments that will never
match.

Hint: It can be safely removed.

Thank you Giacomo Cavalieri for these improvements! Exhaustiveness checking is a very complex field, so these additions are very impressive.

Unused argument detection

Gleam's unused code detection and purity tracking emits a warning any time some code is unused and could be removed without changing the behaviour of the program.

This has been extended to be able to identify function arguments that are used when the function calls itself recursively, but never actually used in the function's implementation. For example:

import gleam/io

pub fn greet(x, times) {
  case times {
    0 -> Nil
    _ -> {
      io.println("Hello, Joe!")
      greet(x, times - 1)
    }
  }
}

In this piece of code the x argument is unused, so the compiler will raise the following warning:

warning: Unused function argument
  ┌─ /Users/giacomocavalieri/Desktop/prova/src/prova.gleam:3:14
  │
3 │ pub fn greet(x, times) {
  │              ^ This argument is unused

This argument is passed to the function when recursing, but it's never
used for anything.

Thank you Giacomo Cavalieri!

Better meaningless opaque type error

A public custom type can be marked as "opaque", meaning that while other modules can import and reference the type, they are unable to construct or pattern match on values of that type. This is useful for restricting the ways that a data type can be used in order to provide a more robust API.

pub opaque type Permission {
  SuperUser
  Regular
  Restricted
}

It is invalid to mark a private type as opaque. Previously this would result in a slightly cryptic syntax, but now a specific helpful error has been added for this case.

error: Private opaque type
  ┌─ /src/one/two.gleam:2:1
  │
2 │ opaque type Wibble {
  │ ^^^^^^ You can safely remove this.

Only a public type can be opaque.

The language server now also offers a "quick fix" code action to remove opaque from a private type:

opaque type Wibble {
// ^^^ This is an error!
  Wobble
}

If you hover over the type and trigger the quick fix, the language server will automatically remove the opaque keyword:

type Wibble {
  Wobble
}

Thank you Giacomo Cavalieri!

More fault tolerance

Giacomo Cavalieri and sobolevn have improved the compiler to be fault tolerant for errors relating to analysis of labeled fields in variant patterns, parsing of private opaque type definitions, and parsing of type names followed by (), further improving the experience of using the Gleam language server.

Thank you both!

Redundant pattern alias warning

_ as x is a valid pattern in Gleam. The _ means "don't assign any name to this value", and the as x part means "assign the name x to this value".

As you can see, this is quite a silly pattern. The alias as pattern makes the discard _ pattern redundant, and it would always be better to use the pattern x, which means "assign this value to the name x".

// Redundant
let _ as x = something()

// Recommended
let x = something()

Using an alias pattern with a discard pattern has been deprecated, and the Gleam code formatter will rewrite any instances of it to the recommended syntax.

Thank you eutampieri for this!

More warnings for inefficient list use

Gleam's basic sequence type is an immutable linked list with structural sharing, a data type inherited from Erlang and one common in functional programming languages.

The correct way to check if a list is empty is to pattern match on it with the empty-list pattern, or to compare it to an empty list literal.

pub fn both_empty(list1: List(a), list2: List(b)) -> Bool {
  // Pattern matching approach.
  // More verbose, but can be part of a larger pattern match.
  let list1_empty = case list1 {
    [] -> True
    _ -> False
  }

  // Comparison approach.
  let list2_empty = list2 == []

  list1_empty && list2_empty
}

The standard library's list.length function returns the length of a given list. Gleam and Erlang lists don't store the length on them as a static property, so this function has to traverse the full list, and count the number of elements, making it a very wasteful way to determine if a list is empty.

This behaviour may be surprising to programmers familiar with languages with a different core sequence data type, so they might not realise this is not a good way to check for an empty list. To remove this confusion the compiler would emit a warning for code like list.length(items) == 0, informing the programmer of better alternatives.

With this release the warning will also be emitted for more inefficient use of list.length, including checks for non-empty lists using operators like > and <.

warning: Inefficient use of `list.length`
  ┌─ /data/data/com.termux/files/home/test_gleam/src/test_gleam.gleam:5:13
  │
5 │     let _ = 0 < list.length(numbers)
  │             ^^^^^^^^^^^^^^^^^^^^^^^

The `list.length` function has to iterate across the whole
list to calculate the length, which is wasteful if you only
need to know if the list is empty or not.

Hint: You can use `the_list != []` instead.

Thank you Andrey Kozhev!

A helpful syntax error for JavaScripters

In Gleam names are assigned to values within functions using the let keyword. There is a const keyword too, but it is used to declare module-level constants, and it is a syntax error to use it within functions.

The compiler now provides a helpful error message for any programmers accustomed to languages where const is used within functions, such as JavaScript.

pub fn deep_thought() -> Int {
  const the_answer = 42
  the_answer
}

error: Syntax error
  ┌─ /src/file.gleam:2:3
  │
3 │   const the_answer = 43
  │   ^^^^^ Constants are not allowed inside functions

All variables are immutable in Gleam, so constants inside functions are not
necessary.
Hint: Either move this into the global scope or use `let` binding instead.

Thank you Surya Rose!

A helpful error for Rustaceans, C#ers, and friends

Gleam has a consistent syntax for constructors at the type and value level, using () for both. It does not use () for value constructors and <> for type constructors, as is common in some other languages.

To help folks coming from other languages a set of helpful errors have been added for when they try to use this non-Gleam syntax in their Gleam code.

error: Syntax error
  ┌─ /src/parse/error.gleam:2:12
  │
2 │ type Either {
  │            ^ I was expecting `(` here.

Type parameters use lowercase names and are surrounded by parentheses.

    type Either(a, b) {

See: https://tour.gleam.run/data-types/generic-custom-types/

Notice how the error message includes the correct syntax for the specific code that the programmer has written. The programmer could copy/paste the correct version into their code, if they so desired. A link to the documentation is also provided, linking to whichever feature the syntax error is for.

Thank you Aaron Christiansen!

A helpful syntax error for Pythonistas, Elixirists, and friends

Similar to the last two new error messages, there's now a helpful error message for programmers trying to use # instead of // to write a comment. Thank you sobolevn!

Displaying dependency version information

Gleam's build tool integrates with Hex, the package management system and primary package repository for the BEAM ecosystem. Gleam implements dependency version locking to ensure that builds are deterministic, and to prevent unaudited code from unexpectedly becoming part of your application. Dependency code is just as much of a risk and responsibility as code directly written by the programmer, so it must be treated with great care and consideration.

The only time the build tool will select new versions of dependency packages is if the programmer adds or removes a dependency, if the programmer changes the package's dependency version requirements, or if the programmer requests the dependency versions be upgraded using the gleam update command.

In these cases when dependencies are changed, added, or removed the build tool will now print the changes, to help the programmer understand and go on to audit the new code.

$ gleam add lustre
  Resolving versions
Downloading packages
 Downloaded 3 packages in 0.04s
      Added gleam_json v3.0.2
      Added houdini v1.2.0
      Added lustre v5.3.5

`hex owner transfer`

The hex owner transfer command has been added to the build tool, allowing Gleam programmers to transfer ownership of existing Hex packages to another account. Thank you Giacomo Cavalieri!

Improved type displaying

When a Gleam package is published to Hex HTML documentation is generated and published to the HexDocs documentation hosting website. This documentation has now been improved to now print the names of public type aliases instead of internal type names when annotating functions and types. This makes the documentation more likely to use the APIs that the package author intends for their users.

For example, for the following code:

import my_package/internal

pub type ExternalAlias = internal.InternalRepresentation

pub fn do_thing() -> ExternalAlias { ... }

This is what the build tool used to generate:

pub fn do_thing() -> @internal InternalRepresentation

This is technically correct, but not very useful for the reader of the documentation, as they cannot learn anything about these internal types. Now it will not use the internal name, allowing the programmer to click-through to its documentation, and understand how they should refer to this type in their code.

pub fn do_thing() -> ExternalAlias

This improvement also applies to the language server, both in information displayed on hover, and in code actions such as "add annotations".

import lustre/html
import lustre/element
import lustre/attribute

pub fn make_link(attribute, element) {
  html.a([attribute], [element])
}

If the "add annotations" code action is run on this function the language server will identify that the imported lustre/attribute module has public export of the Attribute type, and that the imported lustre/element module has public export of the Element type, so they will both be used instead of the internal definition.

pub fn make_link(
  attribute: attribute.Attribute,
  element: element.Element(a)
) -> element.Element(a) {
   html.a([attribute], [element])
}

Thank you Surya Rose!

Improved type naming in code actions

Another way in which code actions need to consider type names is with type parameters. The "add type annotations" and "generate function" code actions must find names for any type variables that do not clash with any already in use. Previously the language server would track names in-use at the module level which could result in correct but unexpected names being used.

Take this code, for example.

fn something(a: a, b: b, c: c) -> d { todo }

fn pair(a, b) { #(a, b) }

Previously, when triggering the "Add type annotations" code action on the pair function, the language server would have used these names:

fn pair(a: e, b: f) -> #(e, f) { #(a, b) }

However in 1.13, it will now use these names:

fn pair(a: a, b: b) -> #(a, b) { #(a, b) }

Thank you Surya Rose!

Tangled support

Tangled is a new open source source forge, and the Gleam build tool now has support for it. When specified the HTML documentation will include links to the source code definitions for each type and value in the package, as it would for previously supported source forges such as GitHub and Forgejo.

repository = { type = "tangled", user = "me", repo = "my_project" }

Thank you to Naomi Roberts for this. As part of this work she added support for links to multi-line sections of code in Tangled itself!

Further language server support

The language server was missing support for a few syntaxes, this has now been fixed. You can now go to definition, rename, etc. from alternative patterns in case expressions:

case wibble {
  Wibble | Wobble -> 0
  //         ^- Previously you could not trigger actions from here
}

And hovering over a record field in a record access expression will now show the documentation for that field, if any exists.

Thank you Surya Rose and fruno!

Remove unreachable clauses code action

Gleam's pattern matching analysis can identify any clauses of a case expression are unreachable due to previous patterns already matching any values the redundant one could match.

pub fn main() {
  case find_user() {
    Ok(person) -> todo
    Ok(Admin) -> todo
    Ok(User) -> todo
    Error(_) -> todo
  }
}

Here the Ok(Admin) and Ok(User) patterns could never match as all the Ok values would be instead matched by the earlier Ok(person) pattern.

This is clearly a mistake in the code, so the compiler will emit a warning and highlight the unreachable clauses. Most commonly the programmer will want to edit the patterns to correct them, but some times the clauses are no longer needed, and can be deleted entirely. To help with this scenario the language server now offers a quick-fix code action to delete any redundant clauses.

Triggering it on the above code will result in the code being edited like so:

pub fn main() {
  case find_user() {
    Ok(person) -> todo
    Error(_) -> todo
  }
}

Thank you Giacomo Cavalieri!

Pattern match on value code action improvements

Gleam has a single flow-control feature: pattern matching with the case expression. Because of this there's a lot of pattern matching in Gleam programs! The language server offers a code action to quickly pattern match on a focused value, and with this release it has been further improved.

It can now be triggered on lists, with the default clauses including one for when the list is empty, and one for when it is non-empty.

pub fn is_empty(list: List(a)) -> Bool {
  //            ^^^^ Triggering the action here
}

Triggering the action over the list argument would result in the following code:

pub fn is_empty(list: List(a)) -> Bool {
  case list {
    [] -> todo
    [first, ..rest] -> todo
  }
}

The code action can now be triggered on variables introduced by other patterns. For example, here we have a let statement with a pattern defining the variables name and role.

pub fn main() {
  let User(name:, role:) = find_user("lucy")
  //              ^^^^ Triggering the action here
}

Triggering the action on role results in a case expression being inserted on the line below, with a clause for each of the possible variants of the Role type that variable held.

pub fn main() {
  let User(name:, role:) = find_user("lucy")
  case role {
    Admin -> todo
    Member -> todo
  }
}

If the variable was introduced within a case expression already then the behaviour is different. For example:

pub fn main() {
  case find_user() {
    Ok(user) -> todo
    Error(_) -> todo
  }
}

Triggering the code action on the user variable would cause the code to be rewritten to expand that clause of the case expression, replacing it with one specialised clause for each of the possible variants of the type of that variable.

pub fn main() {
  case find_user() {
    Ok(Admin) -> todo
    Ok(Member) -> todo
    Error(_) -> todo
  }
}

Thank you Giacomo Cavalieri! Pattern matching is such an important core feature of Gleam that these improvements make a big difference to the experience of writing and editing Gleam code.

Collapse nested case expressions code action

Another new code action is one to collapse nested case expressions into one, reducing nesting and enabling further optimisations in some situations.

case user {
  User(name:) ->
    case name {
      "Joe" -> "Hello, Joe!"
      _ -> "Hello there!"
    }
  Guest -> "You're not logged in!"
}

Triggering the code action on the first clause will result in it being replaced by multiple clauses that produce the same behaviour as the nested version.

case user {
  User(name: "Joe") -> "Hello, Joe!"
  User(name: _) -> "Hello there!"
  Guest -> "You're not logged in!"
}

Thank you Giacomo Cavalieri!

Add omitted labels code action

Function parameters and record fields can have labels, names that can be used at the call-site to make it clearer what each argument is, and to make the ordering of the arguments not matter. The language server now offers a code action to add the omitted labels in a call. For example:

pub type User {
  User(first_name: String, last_name: String, likes: List(String))
}

pub fn main() {
  let first_name = "Giacomo"
  User(first_name, "Cavalieri", ["gleam"])
}

Triggering the code action on the User constructor will result in the language server adding the labels to the arguments.

pub type User {
  User(first_name: String, last_name: String, likes: List(String))
}

pub fn main() {
  let first_name = "Giacomo"
  User(first_name:, last_name: "Cavalieri", likes: ["gleam"])
}

Inter-module generate function code action

The "Generate function" code action now works when the missing function is to be defined in another module. For example:

// src/maths.gleam
pub fn add(a: Int, b: Int) -> Int { a + b }

// src/app.gleam
import maths

pub fn main() -> Nil {
  echo maths.add(1, 2)
  echo maths.subtract(2, 1)
  Nil
}

The app module is calling a function called subtract from the maths module, but that function doesn't exist. Triggering the code action on the call to maths.subtract will edit the maths.gleam file to add the outline of the function, for the programmer to complete.

pub fn add(a: Int, b: Int) -> Int { a + b }

pub fn subtract(int: Int, int_2: Int) -> Int {
  todo
}

Thank you Surya Rose! This is a nice little quality-of-life improvement for Gleam programmers.

Extract function code action

And the last code action of this release, one that has been eagerly anticipated for some time by many Gleam programmers: extract function.

const head_byte_count = 256

pub fn get_head_of_file() {
  let assert Ok(contents) = read_file()
  case contents {
    <-size(head_byte_count), _:bits>> -> Ok(head)
    _ -> Error(Nil)
  }
}

If you were to select the case expression in your editor and trigger the code action, then it would be extracted to a new function, like so:

const head_byte_count = 256

pub fn get_head_of_file() {
  let assert Ok(contents) = read_file()
  function(contents)
}

fn function(contents: BitArray) -> Result(BitArray, Nil) {
  case contents {
    <-size(head_byte_count), _:bits>> -> Ok(head)
    _ -> Error(Nil)
  }
}

Unfortunately the language server protocol design is rather limiting, so the Gleam language server cannot prompt the programmer for a suitable name, it has to use a meaningless name instead. The "rename" feature of the language server can be triggered to give it a more appropriate name.

I believe that Microsoft's rewrite of the TypeScript toolchain will include it using the language server protocol instead of their custom protocol, so hopefully this will result in them expanding the LSP specification to include features their custom protocol has, such as code actions being able to ask for more information.

Thank you again Surya Rose!

Formatter improvements

Gleam has a code formatter that can clean up a file of Gleam code in an instant, freeing up time that would be otherwise spent on the busy-work of manually laying out code. Typically it is run by the programmer's text editor when a file is saved. Several improvements have been made to it with this release.

Bools can be negated with the ! operator, and ints can be negated with the - operator. Negating a value multiple times is redundant and does nothing, so the formatter now collapses duplicate negations.

pub fn useless_negations() {
  let lucky_number = --11
  let lucy_is_a_star = !!!False
}

The code is rewritten like so:

pub fn useless_negations() {
  let lucky_number = 11
  let lucy_is_a_star = !False
}

Additionally, the formatter no longer removes blocks from case clause guards, as the programmer may wish to include them to make code clearer, even if they are not required according to Gleam's operator precedency rules. This also makes the behaviour consistent with the formatting of regular expressions in Gleam functions.

Thank you Giacomo Cavalieri!

And the rest

And thank you to the bug fixers and experience polishers: Andrey Kozhev, Benjamin Peinhardt, Danielle Maywood, fruno, Giacomo Cavalieri, Joohoon Cha, Matias Carlander, Surya Rose, and Tristan-Mihai Radulescu).

For full details of the many fixes and improvements they've implemented see the changelog.

A call for support

Gleam is not owned by a corporation; instead it is entirely supported by sponsors, most of which contribute between $5 and $20 USD per month, and Gleam is my sole source of income.

Thank you to all our sponsors! And special thanks to our top sponsors:

Try Gleam

No more dependency management headaches

2025-08-05T00:00:00Z

Gleam is a type-safe and scalable language for the Erlang virtual machine and JavaScript runtimes. Today Gleam v1.12.0 has been published. Let's take a look at the highlights.

Understanding dependency conflicts

Gleam packages use semantic versioning, and they specify what ranges of releases they are compatible with to ensure that all selected versions are compatible with each other. This is very useful in ensuring that you don't end up stuck with invalid versions that cause the project to fail to compile, or are broken in more confusing subtle ways.

This does, however, mean that sometimes you will have conflicts when adding a dependency, as there's no version which is compatible with the existing versions you have locked. Historically this has been very confusing as we've haven't able to display much useful information when this happens.

error: Dependency resolution failed

An error occurred while determining what dependency packages and
versions should be downloaded.
The error from the version resolver library was:

Unable to find compatible versions for the version constraints in your
gleam.toml. The conflicting packages are:

- app
- wisp
- mist
- gleam_otp
- gleam_json

It's not clear at all what the problem is, or what the programmer might need to do to resolve the problem. This is not fun for them at all.

Thanks to a lot of hard work from Jak and a new release of the underlying pubgrub version solving algorithm library Gleam will now provide much clearer error messages:

error: Dependency resolution failed

There's no compatible version of `gleam_otp`:
  - You require wisp >= 1.0.0 and < 2.0.0
    - wisp requires mist >= 1.2.0 and < 5.0.0
    - mist requires gleam_otp >= 0.9.0 and < 1.0.0
  - You require lustre >= 5.2.1 and < 6.0.0
    - lustre requires gleam_otp >= 1.0.0 and < 2.0.0

There's no compatible version of `gleam_json`:
  - You require wisp >= 1.0.0 and < 2.0.0
    - wisp requires gleam_json >= 3.0.0 and < 4.0.0
  - You require gleam_json >= 2.3.0 and < 3.0.0

Version solving is (perhaps unexpectedly) a very difficult problem! This was not a trivial improvement to make so a huge thank you to Giacomo Cavalieri and the pubgrub library maintainers.

Major update notifications

Another part of the dependency puzzle is knowing when there is a new major version of any of the dependencies. Typically Gleam packages permit a range of minor and patch versions, but not new major versions as according to semver they have breaking changes, so they may not be compatible.

[dependencies]
lustre = ">= 5.2.0 and < 6.0.0"

When there's a new major version the programmer will need to check if the package is compatible, and to adjust the code for the new version if necessary.

To make it easier to understand when this needs to be done the gleam update, and gleam deps download commands will now print a message when there are new major versions of packages available. For example:

$ gleam update
  Resolving versions

The following dependencies have new major versions available:

gleam_http 1.7.0 -> 4.0.0
gleam_json 1.0.1 -> 3.0.1
lustre     3.1.4 -> 5.1.1

Thank you Amjad Mohamed for this!

Future dependency management improvements

Dependency packages can be extremely useful for being productive when programming, but great care must be taken with them, both within a single project and across the wider ecosystem. We want the experience of using packages to be enjoyable and beneficial, and want to avoid developers getting stuck in "dependency hell". In the coming releases we will provide new features that help with managing and auditing dependencies, resolving version conflicts, and to ensure that code published to the package manager is high quality and suitable for production use as much as possible.

Echo messages

Gleam has a convenient echo keyword that is used for quick print-debugging. Put it in front of an expression and it'll print the value and the source location to the console. It returns the value it prints, so it can be inserted anywhere in the code and not change the semantics of the code. There's even a language server code action for removing all echos from a module once you are done debugging.

It is now possible to add a custom message to be printed by echo, so you can add additional information to aid with your debugging.

pub fn main() {
  echo 11 as "lucky number"
}

/src/module.gleam:2 lucky number
11

I've also improved the way that echo displays character lists in Erlang, and circular references and error instances in JavaScript, which should be greatly useful for folks working with code written in these languages.

Thank you Giacomo Cavalieri!

Code size reduction

We've made numerous improvements to Gleam's code generation pipeline which have resulted in the final output being smaller. This is especially impactful when compiling to JavaScript to be used in a web browser as there's an initial cost to downloading JavaScript programs, especially on lower power devices or with poor network connectivity.

Code generated for the record update syntax will now reuse existing variables when possible, reducing the size of the generated code, the number of variables, and the number of new scopes defined for both Erlang and JavaScript. For example:

pub fn main() -> Nil {
  let trainer = Trainer(name: "Ash", badges: 0)
  battle(Trainer(..trainer, badges: 1))
}

This Gleam code compiled for the Erlang VM would previously generate code like this:

-spec main() -> nil.
main() ->
    Trainer = {trainer, 0, <<"Ash"/utf8>>},
    battle(
        begin
            _record = Trainer,
            {trainer, 1, erlang:element(3, _record)}
        end
    ).

With v1.12's variable reuse this is generated instead:

-spec main() -> nil.
main() ->
    Trainer = {trainer, 0, <<"Ash"/utf8>>},
    battle({trainer, 1, erlang:element(3, Trainer)}).

In addition to these the code generated for a case expression on the JavaScript target has been reduced in size in many cases, and the previous release's improved dead-code detection is now use to avoid generating any code that would go unused in the final program.

These improvements were the work of Surya and myself, thank you Surya Rose!

More flexible list formatting

Gleam comes with an automatic code formatter, which can be run in an editor using the Gleam language server, or from the command line with gleam format. Having a canonical formatter means that all Gleam has the same predictable style, making it easier to read Gleam code, and removing time consuming debates about superficial code style.

Previously the formatter wouldn't give the programmer any control over how lists are formatted, always putting the elements on a single line if they fit within the column limit, or spreading them over multiple lines if it does not. With this release the programmer is given more control! If a list would fit on a single line they can still opt to have it spread over multiple lines.

pub fn my_favourite_pokemon() -> List(String) {
  ["natu", "chimecho", "milotic"]
}

To tell the formatter that this list should be spread over multiple lines a comma can be added before the ], which will cause it to be formatted like so:

pub fn my_favourite_pokemon() -> List(String) {
  [
    "natu",
    "chimecho",
    "milotic",
  ]
}

By removing the trailing comma the formatter will try and fit the list on a single line again.

The formatter will also permit the programmer to control whether to have elements be placed one-per-line, or to try and fit multiple onto a line, and single empty lines within lists will be preserved. This will greatly help with large lists that would benefit from being visually segmented into different parts.

Thank you Giacomo Cavalieri! This change will be very popular, I'm sure.

JSDoc support

JSDoc is the most widely used format for in-code documentation in JavaScript, and it is supported by many editors and programming tools. Documentation comments in Gleam code will now be included in the output using JSDoc syntax when compiling to JavaScript.

Thank you Giacomo Cavalieri!

Unreachable import warnings

While not commonly done as it tends to make code harder to read, it is possible to import a function from another module in an unqualified fashioned, meaning you don't need to add the module. prefix when using the function in the importer module.

If a function or a constant is imported in an unqualified fashion and there is function or constant with the same name defined in the module then the imported value will not be accessible at all, making the import pointless. The compiler now emits a warning in this case, so the programmer can identify and fix the problem.

Thank you Aayush Tripathi!

Discarded variable hints

The compiler can now tell when an unknown variable might be referring to a variable that has been discarded with a _ prefix, providing an helpful error message highlighting it. For example, this piece of code:

pub fn go() {
  let _x = 1
  x + 1
}

Now results in the following error:

error: Unknown variable
  ┌─ /src/one/two.gleam:4:3
  │
3 │   let _x = 1
  │       -- This value is discarded
4 │   x + 1
  │   ^ So it is not in scope here.

Hint: Change `_x` to `x` or reference another variable

This new error message also shows off the improved format for secondary labels in warnings and errors, which provide context for the error message. They are highlighted in a distinct fashion to show they are secondary, and in language server clients they will be shown as additional information attached to the diagnostic.

Thank you Giacomo Cavalieri for these!

Avoiding extra object allocations

It is not uncommon when pattern matching to have case clauses where the pattern and the clause match exactly. These clauses cause the value to be passed through unchanged, as can be seen here in the Error clause of this code.

pub fn find_book() -> Result(Book, LibraryError) {
  case ask_for_isbn() {
    Error(error) -> Error(error)
    Ok(isbn) -> load_book(isbn)
  }
}

Previously the generated code for this would construct a new Error to contain the pattern matched error value. With this release the compiler identifies that the resulting value would be identical to the pattern matched value and instead reuses that value. It is safe to do this because Gleam is an immutable language.

Thank you Giacomo Cavalieri!

Redundant comparison warnings

The compiler now emits a warning when performing a redundant comparison that it can tell is always going to succeed or fail. For example, this piece of code:

pub fn find_line(lines) {
  list.find(lines, fn(x) { x == x })
}

Would result in the following warning:

warning: Redundant comparison
  ┌─ /src/warning.gleam:2:17
  │
1 │   list.find(lines, fn(x) { x == x })
  │                            ^^^^^^ This is always `True`

This comparison is redundant since it always succeeds.

Thank you Giacomo Cavalieri!

Helpful import errors for Pythonistas

When learning a new language it can be common to make mistakes with the syntax, especially with syntax that is similar but not the same as another language the programmer is more familiar with.

Gleam's module import syntax looks similar to Python's, but it uses / instead of . in the module name. The compiler now emits a helpful message when this mistake is made.

error: Syntax error
  ┌─ /src/parse/error.gleam:1:11
  │
1 │ import one.two.three
  │           ^ I was expecting either `/` or `.{` here.

Perhaps you meant one of:

    import one/two
    import one.{two}

Thank you Zij-IT!

Helpful list errors for JavaScripters

Similarly a programmer learning a new language may attempt to use a feature their other language has that their new language does not.

Gleam has a syntax for prepending to a list, which is similar to JavaScript's array spread syntax, but faster as it doesn't need to allocate a whole new array and copy the elements across. One big difference to the JavaScript feature is that it is only for prepending, which can be unexpected for JavaScript programmers. A helpful error message is now emitted if the programmer tries to use it to concatenate two lists together.

pub fn main() -> Nil {
  let xs = [1, 2, 3]
  let ys = [5, 6, 7]
  [1, ..xs, ..ys]
}

error: Syntax error
  ┌─ /src/parse/error.gleam:5:13
  │
5 │   [1, ..xs, ..ys]
  │       --    ^^ I wasn't expecting a second list here
  │       │
  │       You're using a list here

Lists are immutable and singly-linked, so to join two or more lists
all the elements of the lists would need to be copied into a new list.
This would be slow, so there is no built-in syntax for it.

Thank you Carl Bordum Hansen and Giacomo Cavalieri.

Argument labels hints in errors

The error message emitted when a function is called with the wrong number of arguments has been improved, it now show the labels for the missing arguments.

error: Incorrect arity
  ┌─ /src/main.gleam:6:3
  │
6 │   Pokemon(198, name: "murkrow")
  │   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Expected 3 arguments, got 2

This call accepts these additional labelled arguments:

  - moves

Thank you Giacomo Cavalieri!

Bit array improvements

Gleam has an expressive literal syntax for constructing and pattern matching on binary data, as is common for languages on the Erlang VM. This syntax is supported when compiling to JavaScript too.

The endianness of a segment can now be specified when constructing or pattern matching on UTF codepoints in bit arrays.

Calculations are now allowed in the size options of bit array patterns. For example, the following code is now valid:

let assert <-size(size / 8 - 1)>> = some_bit_array

Thank you Surya Rose!

Erlang local function inlining

When compiling for the Erlang VM the Gleam build tool will use the Erlang compiler to produce BEAM bytecode for the Gleam code, so Gleam benefits from all the optimisations that it includes.

One option that is disabled by default is inlining of functions within the same module. This Gleam release enables it with conservative configuration that should result in no increase in generated code size. Some BEAM programs will see a notable increase in performance thanks to this.

Thank you Giacomo Cavalieri!

Monorepo code links support

Gleam generates and publishes HTML documentation for packages as they are published to Hex, the BEAM ecosystem package manager. In the documentation there are links to the code for types and functions, so you can see how they are defined after you have read their documentation.

To support this Gleam expects a git tag to be added to each published release, and will help you to do so. However, this system didn't work for monorepos that contain multiple Gleam projects, as the tags could clash.

The repository section in gleam.toml now allows specifying the tag-prefix property, which is prepended to the default tag. This prefix allows the programmer to avoid tag clashes for the different packages in a monorepo

Thank you Sakari Bergen!

CommonJS module support

Some Gleam packages may include JavaScript or Erlang modules which are used with Gleam's "external function" FFI functionality. With this release you can now include JavaScript modules with the .cjs file extension, which enables use of the CommonJS import system.

Thank you yoshi!

Remove block code action

The language server now offers a code action to remove blocks that wrap a single expression. For example, in this code snippet:

case greeting {
  User(name:) -> { "Hello, " <> name }
  //             ^^^^^^^^^^^^^^^^^^^^^ Triggering the code action
  //                                   with the cursor over this block.
  Anonymous -> "Hello, stranger!"
}

Would be turned into:

case greeting {
  User(name:) -> "Hello, " <> name
  Anonymous -> "Hello, stranger!"
}

Thank you Giacomo Cavalieri!

And the rest

And thank you to the bug fixers and experience polishers: Aayush Tripathi, cysabi, Giacomo Cavalieri, Louis Pilfold, and Surya Rose.

For full details of the many fixes and improvements they've implemented see the changelog.

A call for support

Gleam is not owned by a corporation; instead it is entirely supported by sponsors, most of which contribute between $5 and $20 USD per month, and Gleam is my sole source of income.

Thank you to all our sponsors! And special thanks to our top sponsors:

Try Gleam

Gleam JavaScript gets 30% faster

2025-06-02T00:00:00Z

Gleam is a type-safe and scalable language for the Erlang virtual machine and JavaScript runtimes. Today Gleam v1.11.0 has been published.

30% faster? Really?

The title of this article makes a bold claim: Gleam compiled to JavaScript being 30% faster! Gleam doesn't add any additional runtime when compiling to JavaScript, and the generated code is very much like the JavaScript a human would write, so this is an accomplishment we're very happy with.

First, a benchmark. Lustre is a frontend web framework for Gleam, capable of both SPA style and LiveView style functionality. It has a virtual DOM implementation with comparable performance to established frameworks in other languages, such as React and Elm. It is one of the most widely used Gleam packages, and certainly the most widely used Gleam web framework.

Lustre's virtual DOM diffing is implemented in Gleam, so improving its performance will benefit many Gleam users, and it will serve as a good benchmark to demonstrate the improvements. The charts below show the number of operations per second for diffing HTML tables of various sizes (higher is better).

10 rows

v1.10.0
142k
v1.11.0
208k

100 rows

v1.10.0
15.9k
v1.11.0
21.5k

1000 rows

v1.10.0
1.5k
v1.11.0
2.1k

Without any modification to Lustre itself it has got 30% faster! All other Gleam projects compiling to JavaScript can expect to similar performance improvements, with greater improvements to projects with more complex pattern matching.

OK, how does it work?

Gleam has a single flow control construct, the case expression. It runs top-to-bottom checking to see which of the given patterns match the value.

pub fn greet(person: Person) -> String {
  case person {
    Teacher(students: [], ..) -> "Hello! No students today?"
    Student(name: "Daria", ..) -> "Hi Daria"
    Student(subject: "Physics", ..) -> "Don't be late for Physics"
    Teacher(name:, ..) | Student(name:, ..) -> "Hello, " <> name <> "!"
  }
}

Prior to this release, when compiling to JavaScript code results in if else chain, as can be seen in the code below.

export function greet(person) {
  if (isTeacher(person) && isEmpty(person.students)) {
    return "Hello! No students today?";
  } else if (isStudent(person) && person.name === "Daria") {
    return "Hi Daria";
  } else if (isStudent(person) && person.subject === "Physics") {
    return "Don't be late for Physics";
  } else if (isTeacher(person)) {
    return "Hello, " + person.name + "!";
  } else {
    return "Hello, " + person.name + "!";
  }
}

Disclaimer: This code has been lightly edited for clarity, but all aspects related to this implementation change remain the same.

This is very understandable and human looking code, but it's not as efficient as possible. For example, if the value is a Student with a name other than "Daria" and a subject other than "Physics" then the isTeacher and isStudent functions are each called twice, resulting in wasted work. Similar problems arise with other patterns, especially with the list type as it would need to be traversed multiple times to check various elements within them.

The new and improved approach is to transform the linear sequence of checks into a decision tree, where each check is performed the minimum number of times to find the matching clause as quickly as possible. This decision tree is then compiled into a series of nested if else statements in JavaScript.

export function greet(person) {
  if (isTeacher(person)) {
    if (isEmpty(person.students)) {
      return "Hello! No students today?";
    } else {
      return "Hello, " + person.name + "!";
    }
  } else {
    if (person.name === "Daria") {
      return "Hi Daria";
    } else {
      if (person.subject === "Physics") {
        return "Don't be late for Physics";
      } else {
        return "Hello, " + person.name + "!";
      }
    }
  }
}

This does result in a small increase in code size (up to 15% in our tests), but the uniform nature of the extra code is well suited to compression, with minification and brotli compression completely removing this extra size and producing the same application bundle size as with previous Gleam versions.

We have only implemented this optimisation for the JavaScript target and not the Erlang one as the Erlang Virtual machine implements this optimisation itself! It is done for us automatically there.

As part of this work the compilers analysis of pattern matching was enhanced, notably around bit-array patterns. It can now identify when a clause with a bit array pattern is unreachable because it only matches values that a previous clause also matches, such as the second clause here:

case payload {
  <> -> first_byte
  <<1, _:bits>> -> 1
  _ -> 0
}

Efficient compilation of pattern matching is a surprisingly challenging problem, and we would not have had so much success without academic research on the subject. In particular we would like to acknowledge "How to compile pattern matching", by Jules Jacobs and "Efficient manipulation of binary data using pattern matching", by Per Gustafsson and Konstantinos Sagonas. Thank you.

This is the culmination of work that was started before Gleam v1, and has been desired for much longer. A huge thank you to Giacomo Cavalieri for this final piece.

But that's not all! There's lots more new things in this release. Let's take a look.

Testing with `assert`

Types and static analysis are wonderful tools to help you write code, but you're always going to need to test programs to know they are working correctly. Gleam the language historically doesn't have any built-in testing functionality, so test libraries define assertion functions that can be used in tests.

pub fn hello_test() {
  telephone.ring()
  |> should.equal("Hello, Joe!")
}

This has worked well enough to be productive, but it's not the world-class experience we want in Gleam. These assertion functions are just that: they are functions. All they can do is take arguments and return values. They can't know anything about the code that produced those arguments, or the context from which they are being called. The debugging information that a Gleam test framework can provide with this is quite limited to compared to other languages that have either built-in assertion capabilities, a macro system, or other similar features.

Gleam isn't a language about types, it's a language about productivity and developer joy. This sub-par testing experience wasn't up to our high standards, and with this release we've made a big step towards correcting that with the addition of assert.

pub fn hello_test() {
  assert telecom.ring() == "Hello, Joe!"
}

This new syntax panics if the given expression evaluates to False. What makes it different to conditionally calling the existing panic syntax is that the runtime error is annotated with information about the expression that evaluated to False, so test frameworks can provide detailed debugging information in the event of a test failure.

Here's the output that the gleeunit test framework will use. Other Gleam test frameworks may go further with even better formats!

...............
assert test/my_app_test.gleam:215
 test: my_app_test.hello_test
 code: assert telecom.ring() == "Hello, Joe!"
 left: "Hello, Mike!"
right: literal
 info: Assertion failed.
..........
25 tests, 1 failures

Note how the test framework has enough information to show the assertion code as it was written in the source file, and can show the values for the left and right of the == operator.

As well as operators it can also understand function calls and show what each argument is.

........
assert test/my_app_test.gleam:353
 test: my_app_test.system_test
 code: assert telecom.is_up(key, strict, 2025)
    0: "My WIFI"
    1: True
    2: literal
 info: My internet must always be up!
.................
25 tests, 1 failures

In that example there was a custom assertion message, displayed under the info key. This is provided the same way as custom messages for Gleam's todo and panic syntaxes, using the as keyword.

pub fn system_test() {
  let key = "My WIFI"
  let strict = True

  assert telecom.is_up(key, strict, 2025)
    as "My internet must always be up!"
}

Upgrading from gleeunit's assertion functions to the new assert syntax is a slow and tedious job for a human to do, so Gears has made a helpful command line tool to do it automatically! Run it and your codebase will be updated for you in just a second.

Thank you Surya Rose for this! It will make a big difference to all Gleam programmers testing their programs.

`gleam dev`

A Gleam application typically has two main functions, one in src/ for running the application, and one in test/ for running the tests. The application main function can be run with the console command gleam run, and the test one with the command gleam test. This is easy enough to understand, but what if you have some other code you need to run in development? For example, if you're making a backend web application you might want to have some extra code that configures a local development database, or compiles some frontend assets. Where would you put the code that does this?

This is development code that you do not want to ship to production (extra code and dependencies is a potential security risk), and having code that can make destructive changes to the database in production is an accident waiting to happen!

The traditional wisdom is to put a new module and main function the test/ directory (as this code isn't included in production) and then to run it with gleam run --module $THE_MODULE. Placing non-test code in a directory called test isn't very intuitive, so it's not uncommon for people to place it in src instead, resulting in development code and dependencies accidentally being published.

This release adds a new source directory for development code, dev/. Code in the dev/ directory can import src/ code and use development dependencies, and the $PACKAGENAME_dev module's main function can be run with the new gleam dev console command. This should hopefully be a more satisfying and easy to understand system, preventing future mistakes.

Thank you Surya Rose!

Help with understanding immutability

Gleam is an immutable language, which means that values are not updated in-place, instead new values are constructed from older values, with the desired changes applied. If you are familiar with mutable languages this may seem inefficient, but immutable languages apply some clever optimisations to get excellent performance and memory usage.

It's possible for people new to the immutable style to get confused, accidentally discarding the new updated version of some data. For example:

pub fn call_api(token: String) -> Response(String) {
  let req = sdk.new_api_request()
  request.set_header(req, "authentication", "Bearer " <> token)
  http_client.send(req)
}

Can you spot the bug?

The set_header function returns a new request value, but it is not assigned to a variable, so the original request value without the authentication header is sent instead. The bug is fixed by passing the output of each function into the next one.

pub fn call_api(token: String) -> Response(String) {
  sdk.new_api_request()
  |> request.set_header("authentication", "Bearer " <> token)
  |> http_client.send
}

To help avoid this mistake the compiler will now emit a warning when a function without any side effects is called but the return value isn't used. For example the following code:

fn go() -> Int {
  add(1, 2)
  add(3, 4)
}

Will produce the following warning:

warning: Unused value
    ┌─ /src/main.gleam:4:3
    │
  4 │   add(1, 2)
    │   ^^^^^^^^^ This value is never used

This expression computes a value without any side effects, but then the
value isn't used at all. You might want to assign it to a variable, or
delete the expression entirely if it's not needed.

Thank you Surya Rose!

JavaScript bit array improvements

Gleam has a powerful literal syntax for constructing and parsing binary data, a much loved feature common to BEAM languages. Gleam supports this syntax when compiling to Erlang or to JavaScript, but some aspects of the syntax were not yet usable on JavaScript. This release adds support for UTF-16 and UTF-32 encoded segments of data.

Thank you Surya Rose!

Playing nicely with POSIX

The Gleam build tool has a gleam export erlang-shipment command for compiling and preparing a project for deployment to a server or similar. It includes a script for starting the Erlang virtual machine and running the program, but unfortunately it was written in a way that meant that the program would not receive POSIX exit signals.

Christopher De Vries has fixed this problem. Thank you Christopher!

Generated documentation improvements

When publishing a package to Hex, the BEAM ecosystem package repository, the Gleam build tool will generate and upload HTML documentation for the code.

When generating documentation, the build tool now prints type variable using the same names as were used in the source code, making it easier to understand what these type parameters are. For example, previously this function would have been rendered like this:

pub fn from_list(entries: List(#(a, b))) -> Dict(a, b)

But now is rendered as the following:

pub fn from_list(entries: List(#(key, value))) -> Dict(key, value)

Another area of the documentation that has been improved is how types imported from other modules are displayed. These types are now displayed with their module qualifiers, and hovering over them shows the full module name. For example, this code:

import gleam/dynamic/decode

pub fn something_decoder() -> decode.Decoder(Something) {
  ...
}

Will now generate the following documentation:

pub fn something_decoder() -> decode.Decoder(Something)

Hovering over the decode.Decoder text will show the following:

gleam/dynamic/decode.{type Decoder}

Clicking on decode.Decoder will take you to the documentation for that type.

Thank you Surya Rose!

Yet more fault tolerance

Gleam's compiler implements fault tolerant analysis. This means that when there is some error in the code that means it is invalid and cannot be compiled, the compiler can still continue to analyse the code to the best of its ability, ignoring the invalid parts. Because of this Gleam language server can have a good understanding of the code and provide IDE feature even when the codebase is in an invalid state.

This release makes the analysis of lists, tuples, negation operators, panic, echo and todo, function parameters, and function labels fault tolerant. We're covering all the last remaining little case to make the language server information as fresh and accurate as possible!

Thank you Giacomo Cavalieri and Surya Rose!

Labels in inexhaustive case expression errors

Gleam has exhaustiveness checking. This means that pattern matching flow control must handle all the possible values that the type being matched on could be. If there are any clauses missing then the program is incomplete, and the compiler will return a helpful error showing the missing patterns.

This error has been improved to include record field labels, as can be seen at the bottom of this example:

error: Inexhaustive patterns
  ┌─ /src/main.gleam:6:3
  │
6 │ ╭   case person {
8 │ │     Teacher(name:) -> io.println("Good morning!")
7 │ │     Student(name: "Samara", age: 27) -> io.println("Hello Samara!")
9 │ │   }
  │ ╰───^

This case expression does not have a pattern for all possible values. If it
is run on one of the values without a pattern then it will crash.

The missing patterns are:

    Student(name:, age:)

This improvement has also upgraded the code action to add missing patterns to a case expression, now when the missing clauses are added to the code they will include record labels.

Thank you Surya Rose!

Fill labels code action for patterns

The language server has a code action for filling in possible labels for a function or record. This can be a convenient time saver when writing code, especially if you can't immediately remember what labels the arguments use.

This code action has been upgraded to also work with records in patterns. In this code the Person record pattern is missing two of its fields, so running the code action will add them for you.

pub type Person {
  Person(name: String, age: Int, job: String)
}

pub fn age(person: Person) {
- let Person(age:) = person
+ let Person(age:, name:, job:) = person
  age
}

Thank you Surya Rose!

Bit array truncation warning

The compiler now raises a warning when it can tell that an int segment with a literal value is going to be truncated. This will help folks understand a behaviour that may be unexpected.

warning: Truncated bit array segment
    ┌─ /src/main.gleam:4:5
    │
  4 │   <<258>>
    │     ^^^ You can safely replace this with 2

This segment is 1 byte long, but 258 doesn't fit in that many bytes. It
would be truncated by taking its first byte, resulting in the value 2.

Thank you Giacomo Cavalieri!

Better language server support for constants

Gleam's language server has historically been missing hover, autocompletion, and go-to definition within constants. Surya Rose has corrected this by implementing these features. Thank you Surya!

Generate function code action improvements

Gleam's language server has a code action for generating the outline of a function that is used in the code but does not yet exist.

It has been upgraded to now choose better argument names based on the labels and variables used. For example, if the code action is run on the not-yet-defined function named remove:

pub fn main() -> List(Int) {
  let list = [1, 2, 3]
  let number = 1
  remove(each: number, in: list)
//^^^^^^ This function doesn't exist yet!
}

The language server will then generate the outline of the missing function, and the code will look like this:

pub fn main() -> List(Int) {
  let list = [1, 2, 3]
  let number = 1
  remove(each: number, in: list)
}

fn remove(each number: Int, in list: List(Int)) -> List(Int) {
  todo
}

Thank you Giacomo Cavalieri!

Generate variant code action

The language server now provides a code action to automatically generate a new custom type variant, similar to the generate function code action.

In this example the UserPressedButton variant does not exist, but the compiler can tell from the way that it is used that if it did exist it would be a variant of the Msg custom type.

pub type Msg {
  ServerSentResponse(Json)
}

pub fn view() -> Element(Msg) {
  div([], [
    button([on_click(UserPressedButton)], [text("Press me!")])
    //               ^^^^^^^^^^^^^^^^^ This doesn't exist yet!
  ])
}

Triggering the code action on the UserPressedButton will add it to the Msg type:

pub type Msg {
  ServerSentResponse(Json)
+ UserPressedButton(String)
}

The code action understood the code well enough to know that this new variant holds a string value, as that is what the on_click function does with it in this example. If the variant was used with labels then the labels would be included in the definition also.

Thank you Giacomo Cavalieri! Another excellent code action for "top-down" style programmers.

Remove unused imports code action improvements

For a long time the Gleam language server has included a code action for removing unused imports, but it wouldn't work as well as desired for imports that include unqualified types and values: they would still remain after running the action.

import a_module.{type Unused, unused, used}

pub fn main() {
  used
}

Triggering the code action will remove all unused types and values:

import a_module.{used}

pub fn main() {
  used
}

Thank you Giacomo Cavalieri!

Windows ARM binaries

We provide precompiled executables for each Gleam release, supporting Windows, macOS, and Linux. Gleam users and package management systems can download and use these executables instead of compiling the Gleam project from scratch, which takes a long time.

Jonatan Männchen has added an ARM64 Windows build. This is useful as ARM based development machines are becoming more and more common. Thank you Jonatan!

And the rest

And thank you to the bug fixers and experience polishers: Ariel Parker, Giacomo Cavalieri, Louis Pilfold, Mathieu Darse, Matias Carlander, Samuel Cristobal, and Surya Rose.

For full details of the many fixes and improvements they've implemented see the changelog.

A call for support

Gleam is not owned by a corporation; instead it is entirely supported by sponsors, most of which contribute between $5 and $20 USD per month, and Gleam is my sole source of income.

Thank you to all our sponsors! And especially our top sponsor: Lambda.

Try Gleam

Global rename and find references

2025-04-14T00:00:00Z

Gleam is a type-safe and scalable language for the Erlang virtual machine and JavaScript runtimes. Today Gleam v1.10.0 has been published. Here's what's new:

Project-wide call reference graph

The compiler has been upgraded to retain more information about the types and values and how they reference each other in Gleam programs. With this information the language server (which is included within the gleam binary) now provides the "find references" feature, so you can find everywhere in your project where a type or value is used.

The additional information has also been used to improve the "rename" language server feature. Previously only module-local types and values could be renamed, but now renaming can be performed across all modules in a project.

Lastly the compiler's unused-code detection has been greatly improved, fixing some situations in which it would fail to detect it all previously.

Thank you to Surya Rose for implementing this! It is probably our most anticipated addition within the community!

Improved exhaustiveness analysis

Gleam's compiler performs exhaustiveness analysis, ensuring that all possible variants of the value are handled in flow control, and that there are no redundant cases which are not reachable due to previous cases.

Giacomo Cavalieri has spent the time since the previous release studying the academic literature on the complex subject of exhaustiveness checking to bring a variety of improvements to our implementation. The first of these changes has made it into this release: string pattern analysis. Previously only rudimentary analysis was performed on strings, and unreachable string patterns could not be detected.

case a_string {
  "Hello, " <> name -> name
  "Hello, Jak" -> "Jak"
  _ -> "Stranger"
}

In this code the first pattern matches all the values that the second pattern matches, so the second pattern is not reachable. The compiler now emits this warning:

warning: Unreachable case clause
  ┌─ /src/greet.gleam:7:5
  │
7 │     "Hello, Jak" -> "Jak"
  │     ^^^^^^^^^^^^^^^^^^^^^

This case clause cannot be reached as a previous clause matches the same
values.

Hint: It can be safely removed.

Thank you Giacomo! Excellent work!

Alongside that the compiler now emits a warning when using let assert to assert a value whose variant has already been inferred, such as in this code:

let e = Error("Some error")
let assert Ok(_) = e // warning: Pattern will never match

Thank you Surya Rose!

Operator analysis improvements

Gleam's compiler is fault tolerant, meaning that when an error is encountered in the code it does not stop immediately, instead it shows the error to the programmer, makes a best-effort attempts to recover and continue analysing the rest of the code. This behaviour is vital for the language server to have information about the code even when it's in an invalid state.

The analysis of binary operators such as + and == have been improved so that both sides will be checked even in the presence errors. This improves language server information in some situations, and it also enables improved error messages.

Gleam doesn't have operator overloading or interfaces, so each operator works with a specific type. For example + is only for adding ints, and string concatenation is done with the <> operator. Previously the error message for the wrong operator would point to the value and say it is of the wrong type, but now it points to the operator itself and tells you what the correct operator would be:

error: Type mismatch
  ┌─ /src/wibble.gleam:2:13
  │
2 │   "Hello, " + "Lucy"
  │             ^ Use <> instead

The + operator can only be used on Ints.
To join two strings together you can use the <> operator.

The language server willl also offer a code action to fix the error for you in your editor.

pub fn main() {
  "Hello, " + "Jak"
//^^^^^^^^^^^^^^^^^ When hovering anywhere over here
}

Triggering the code action would fix the compilation error by using the correct <> operator instead of +:

pub fn main() {
  "Hello, " <> "Jak"
}

Thank you Giacomo Cavalieri!

Bit array improvements

Gleam's bit array literal syntax provides a powerful and convenient way to construct and parse binary data.

It is fully supported when targeting the Erlang virtual machine, but some bit array literals were not fully supported when targeting JavaScript. Surya Rose has added support for the unit option to control the units of the size option, and Richard Viney has added support for 16-bit floats.

Giacomo Cavalieri has made it possible to omit the :float option when used with float literals, as the intention is unambiguous. These two literals are now equivalent, while previously the former would be a type error due to lacking sufficient annotations.

<<1.11>>
<<1.11:float>>

Thank you Surya, Richard, and Giacomo!

JavaScript codegen performance improvements

Surya Rose has improved the JavaScript code generation to make the code run faster. Where possible the compiler restructures code to no longer use JavaScript "immediately invoked function expressions", removing the overhead of allocating and then calling these functions.

This is the first of a series of JavaScript performance improvements we are currently working on, and our initial benchmarks show they will be impactful, improving the performance of all Gleam programs that compile to JavaScript without any modification to the programs themeselves.

Thank you Surya!

Cross platform deployment artefacts

BEAM bytecode is portable. You can compile your Erlang, Elixir, or Gleam program on one machine and run it on another with a different operating system and processor architecture.

One annoyance if you were doing this with Gleam was that the gleam export erlang-shipment command would try to be clever and give you an entrypoint script for the operating system you are currently using, so if you compiled on Windows to run on Linux then you would be missing the POSIX shell entrypoint script.

Greg Burri has resolved this problem by having the build tool include all entrypoint scripts, regardless of the operating system used to build the artefact. Thank you Greg!

Package information export

Rodrigo Álvarez has created the gleam export package-information command, which will write information about a Gleam package to file in JSON format. This information may be useful to other build tools that wish to compile Gleam code, and Rodrigo is exploring adding support for Gleam dependencies to Elixir's Mix build tool.

Thank you Rodrigo! This will be especially exciting for Elixir programmers as many folks use Gleam and Elixir together.

Fill unused fields code action

The language server can now offer a code action to replace a .. in a pattern with all the fields that it was being used to ignore. For example triggering the code action on this code:

pub type Pokemon {
  Pokemon(id: Int, name: String, moves: List(String))
}

pub fn main() {
  let Pokemon(..) = todo
  //          ^ If you put your cursor here
}

Would result in the code being edited like so:

pub type Pokemon {
  Pokemon(id: Int, name: String, moves: List(String))
}

pub fn main() {
  let Pokemon(id:, name:, moves:) = todo
}

Thank you Giacomo Cavalieri!

Improved JSON encoder generation code action

The function generated by the "Generate JSON encoder" code action will now fail to compile if the type has new fields added. The motivation for this may not be immediately clear, so let's dig into that a little.

Gleam's development philosophy is to use static analysis, editor tooling, and other forms of computer assistance to reduce the mental load for the programmer as much as possible. With the previous design if the data type definition was edited the programmer would have to remember about the existance of the JSON encoder, making it possible to forget and accidentally introduce a bug. With the new behaviour this mistake is no longer possible.

Here is an example of a type and the encoder function that the language server will now generate for it. Note the new pattern matching with let.

type Person {
  Person(name: String, age: Int)
}

fn encode_person(person: Person) -> json.Json {
  let Person(name:, age:) = person
  json.object([
    #("name", json.string(name)),
    #("age", json.int(age)),
  ])
}

Thank you Surya Rose!

Remove echo code action

Gleam has the echo keyword for debug printing. It's convenient for quickly understanding runtime behaviour of code, but it should never be included in production code and the build tool will refuse to publish code that uses it.

The language server now offers a code action to remove all echos in a module. For example:

pub fn main() {
  echo 1 + 2
}

Triggering the code action would remove the echo:

pub fn main() {
  1 + 2
}

Thank you Giacomo Cavalieri!

Extract constant code action

The language server now offers the option to lift non-dynamic expressions into constants. If the code action is run on the list literal here:

const lucy = "Lucy"

const nubi = "Nubi"

pub fn main() {
  list.each([lucy, nubi, "Biffy"], io.println)
}

The code is updated like so:

const lucy = "Lucy"

const nubi = "Nubi"

const values = [lucy, nubi, "Biffy"]

pub fn main() {
  list.each(values, io.println)
}

Thank you Matias Carlander!

Wrap in block code action

The language server will offer to wrap assignment or case clause values in blocks. This is is a convenience for when adding more expressions to some existing code that previous only had one expression, making everyday Gleam editing that little bit easier.

For example, with this code:

pub fn f(pokemon_type: PokemonType) {
  case pokemon_type {
    Water -> soak()
    //       ^^^^^^ Cursor within this expression
    Fire -> burn()
  }
}

Triggering the code action results in the code being updated like so:

pub fn f(pokemon_type: PokemonType) {
  case pokemon_type {
    Water -> {
      soak()
    }
    Fire -> burn()
  }
}

Thank you Matias Carlander!

Security and compliance

Gleam's container images now contain Software Bill of Materials (SBoM) and Supply-chain Levels for Software Artifacts (SLSA) Provenance information.

This will greatly help with security audits and compliance of software written with Gleam, and is part of an ongoing effort to evidence production readiness and promote Gleam adoption within enterprise. This is well timed, as Gleam has just featured in the Thoughtworks technology radar for the first time!

Thank you to Jonatan Männchen and the Erlang Ecosystem Foundation for this and their ongoing support of Gleam and Gleam companies.

And the rest

And thank you to the bug fixers and experience polishers: Alexander Keleschovsky, Drew Olson, Giacomo Cavalieri, Louis Pilfold, Matias Carlander, Sakari Bergen, Sam Zanca, Samuel Cristobal, and Surya Rose.

For full details of the many fixes and improvements they've implemented see the changelog.

A call for support

Gleam is not owned by a corporation; instead it is entirely supported by sponsors, most of which contribute between $5 and $20 USD per month, and Gleam is my sole source of income.

Thank you to all our sponsors! And especially our top sponsor: Lambda.

Try Gleam

Hello echo! Hello git!

2025-03-08T00:00:00Z

Gleam is a type-safe and scalable language for the Erlang virtual machine and JavaScript runtimes. Today Gleam v1.9.0 has been published. Let's take a look!

Echo debug printing

There are debuggers you can use with Gleam, however the most popular ways to understand the runtime behaviour of a Gleam program is through writing tests and through print debugging.

The standard library function io.debug is most commonly used for print debugging. It takes a value of any type, uses target specific runtime reflection to turn it into a string of Gleam syntax, and then prints it to standard-error. This works well, but there are some ways in which this function is not optimal:

Functions don't know anything about where they are called from, so it's not possible to print the location of the io.debug call along with the value being printed.
There's no way for the compiler or build tool to know this is a special function which is only for debugging, so they are unable to prevent you from accidentally publishing packages that still have debug code in them.
Runtime reflection is used to make a string representation of the value, so any information that no longer exists after compile time cannot be used. This results in io.debug relying on heuristics to decide how to show the value, and this can be at-times incorrect.

To improve on this the echo keyword has been introduced. Prefix an expression with it and the value will be printed to standard-error, along with the path to the file and line containing the echo expression, so you can click to jump to it in your editor.

pub fn main() {
  echo [1, 2, 3]
}

The output of this program will look like this:

src/main.gleam:2
[1, 2, 3]

It can also be used in pipelines. Here the list returned by the first list.map call will be printed.

pub fn main() {
  [1, 2, 3]
  |> list.map(fn(x) { x + 1 })
  |> echo
  |> list.map(fn(x) { x * 2 })
}

The build tool is aware this is for debugging, so it'll let you know if you forget to remove it before publishing a package for others to use.

Currently it uses the same runtime reflection and heuristics to format the output, but in future it'll be enhanced to make use of the compiler's static analysis.

Thank you Giacomo Cavalieri! We had all manner of annoying CI-related problems when implementing the integration tests for this feature, Jak's a very patient and determined programmer indeed!

Git dependencies

There are times when we wish to try out early prototype versions of libraries we have made in our applications. It may be tempting to publish these unfinished packages to the package manager, but this would be inappropriate! Only production-ready packages should be published for other people to use, the Gleam package ecosystem is to be high quality and easy to depend upon safely.

As a more suitable alternative the build tool now supports depending on packages within git repositories. Add the git or HTTP URL of a repository along with a tag, branch, or commit SHA, and the build tool will download it for you and then treat it like a regular Gleam dependency package.

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

Thank you Surya Rose for this much anticipated feature.

More powerful bit arrays on JavaScript

Gleam's bit array syntax allows you to construct and parse binary data in a way that may be easier to understand than using binary operators. Historically bit arrays had to be byte aligned, meaning they had to have a number of bits that was divisible by 8. Richard Viney has done some incredible work and lifted this limitation. Thank you Richard!

Surya Rose has also been lifting JavaScript bit array restrictions, enabling the usage of dynamically sized segments in bit array patterns. Thank you Surya!

Faster list pattern matching on JavaScript

The list type is one of Gleam's primary data structures, it is used very heavily in Gleam programs. yoshi~ has been working hard to identify potential performance optimisations for the virtual-DOM implementation of the Lustre framework, and in the process they identified a way to improve the JavaScript code we generate when pattern matching on lists.

Programs that compile to JavaScript and make heavy use of list prefix patterns may now be up to twice as fast!

Go-to type definition

Gleam's built-in language server brings IDE-like functionality to all editors that support the language server protocol. It has had support for go-to definition for some time, but with this release Giacomo Cavalieri has added support for go-to type definition. Place your cursor on an expression and trigger the feature and the language server will identify the types of all the values used in the expression and present their definitions for you to view and to jump to. Thank you Jak!

HexDocs search integration

When a Gleam package is published HTML documentation is generated and published to HexDocs for users to read. HexDocs have been improving their search functionality to search for types and functions with in packages themselves, and Diemo Gebhardt has updated Gleam's documentation generator to implement the search index interface so Gleam packages are included in the search. Thank you Diemo!

Another option for searching within Gleam packages is Gloogle, a Gleam community project, which can even search by function type signature.

Custom CA certificates support

Some enterprise networks may perform TLS interception for security reasons. In these environments custom CA certificates must be used as otherwise requests will get TLS errors due to the unknown authority of the injected certificates.

The new GLEAM_CACERTS_PATH environment variable can be used to specify a path to CA certificates for Gleam to use when interacting with the Hex package manager servers, making Gleam usable in these enterprise environments. Thank you winstxnhdw!

Convert to and from pipeline code actions

Gleam's much-loved pipe syntax gives programmers another way to write nested function calls so that they read top-to-botton and left-to-right.

Two new language server code actions have been added to help you refactor between the pipe syntax and regular function call syntax. Triggering them on these two code examples will edit your code to match the other.

import gleam/list

pub fn main() {
  list.map([1, 2, 3], double)
}

import gleam/list

pub fn main() {
  [1, 2, 3] |> list.map(double)
}

You can also choose to pipe arguments other than the first by selecting them in your editor before triggering the code action. Thank you Giacomo Cavalieri!

Generate JSON encoder code action

Many Gleam programs make use of JSON, a common text-based data exchange format. With this release the Gleam language server now offers a code action to generate a function to convert a type into JSON using the gleam_json library. Given this type definition:

pub type Person {
  Person(name: String, age: Int)
}

If the code action is triggered on the type definition this function will be generated:

import gleam/json

fn encode_person(person: Person) -> json.Json {
  json.object([
    #("name", json.string(person.name)),
    #("age", json.int(person.age)),
  ])
}

Thank you Surya Rose for this code action!

Inline variable code action

The Gleam language server now offers a code action that will inline a variable that is used only once.

import gleam/io

pub fn main() {
  let greeting = "Hello!"
  io.println(greeting)
}

If the code action is triggered on the greeting variable the code will be edited like so:

import gleam/io

pub fn main() {
  io.println("Hello!")
}

Thank you Surya Rose!

Generate multi-variant decoder code action

Gleam's Dynamic type represents data of unknown shape that comes from outside of the Gleam program, for example data sent to a HTTP server as JSON. To convert data from dynamic into known Gleam types the decoder API is used.

A previous release added convenient a code action which would generate a dynamic decoder for a given type definition. With this release this code action has been extended to support multi-variant custom types. For example, given this type definition:

pub type Person {
  Adult(age: Int, job: String)
  Child(age: Int, height: Float)
}

If the code action is triggered on it then this function will be generated:

import gleam/dynamic/decode

fn person_decoder() -> decode.Decoder(Person) {
  use variant <- decode.field("type", decode.string)
  case variant {
    "adult" -> {
      use age <- decode.field("age", decode.int)
      use job <- decode.field("job", decode.string)
      decode.success(Adult(age:, job:))
    }
    "child" -> {
      use age <- decode.field("age", decode.int)
      use height <- decode.field("height", decode.float)
      decode.success(Child(age:, height:))
    }
    _ -> decode.failure(todo as "Zero value for Person", "Person")
  }
}

Thank you Surya Rose!

String interpolate code action

The language server now offers a convenient code action to interpolate a value into a string easily. If the cursor is inside a literal string the language server will offer to split it:

"wibble | wobble"
//      ^ Triggering the action with the cursor
//        here will produce this:
"wibble " <> todo <> " wobble"

And if the cursor is selecting a valid Gleam name, the language server will offer to interpolate it as a variable:

"wibble wobble woo"
//      ^^^^^^ Triggering the code action if you're
//             selecting an entire name, will produce this:
"wibble " <> wobble <> " woo"

Thank you Giacomo Cavalieri for this!

Module qualifier hovering

The language server can now show documentation for a module when hovering the module qualifier of an imported type or value. Thank you Surya Rose!

Redundant function capture removal

Gleam's function capture syntax is a shorthand for creating an anonymous function that takes one argument and calls another function with that argument and some other values. These two expressions are equivalent:

let double = fn(number) { int.double(number, 2) }
let double = int.double(_, 2)

If the function capture syntax is used without any additional arguments, then it is redundant and does nothing that referring the function directly wouldn't do.

let print = io.print(_)

The Gleam code formatter will now remove the redundant function capture syntax for you, formatting it like so:

let print = io.print

Thank you Giacomo Cavalieri!

And the rest

And thank you to the bug fixers: Giacomo Cavalieri, LostKobrakai, Louis Pilfold, Mikko Ahlroth Pedro Francisco, PgBiel, Richard Viney, and Surya Rose!

For full details of the many fixes and improvements they've implemented see the changelog.

A call for support

Gleam is not owned by a corporation; instead it is entirely supported by sponsors, most of which contribute between $5 and $20 USD per month, and Gleam is my sole source of income.

Thank you to all our sponsors! And especially our top sponsor: Lambda.

Try Gleam

Gleam gets “rename variable”

2025-02-07T00:00:00Z

Gleam is a type-safe and scalable language for the Erlang virtual machine and JavaScript runtimes. Today Gleam v1.8.0 has been published. Let's take a look!

Rename variables and arguments

The most desired feature for a long time has probably been "rename" in the language server. I'm happy to announce that the first iteration of this has been implemented! Local variables and function arguments can be renamed. For example, given this code:

pub fn main() {
  let wibble = 10
  wibble + 1
}

Triggering the "rename" command in your editor with your cursor on wibble and then entering my_number will cause the language server to edit your code like so:

pub fn main() {
  let my_number = 10
  my_number + 1
}

It's not limited to variables that are used a single time, all the uses will be converted as required. This is just the first iteration of this feature, renaming for other things in Gleam code will come in future releases.

Thank you Surya Rose for this long awaited feature!

Erlang documentation integration

Erlang OTP27 added the -doc attribute, a new standard for adding documentation to Erlang based code. The documentation for functions with this attribute can be programmatically accessed, for example using the documentation helper in the Erlang and Elixir REPLs.

Eshell V15.1.3 (press Ctrl+G to abort, type help(). for help)
1> h(gleam@list, map).

  map(List, Fun)

  Returns a new list containing only the elements of the first list after the
  function has been applied to each one.

Examples

     map([2, 4, 6], fn(x) { x * 2 })
     // -> [4, 8, 12]

As you can see, Giacomo Cavalieri has added support for this attribute in the Gleam code generator, so Gleam documentation can be accessed like this from any BEAM language. The code is generated in such a fashion that it will continue to work with older version of Erlang/OTP also. Thank you Jak!

Generate function code action

The language server can now generate the definition of functions that do not yet exist. For example if I write the following piece of code:

import gleam/io

pub type Pokemon {
  Pokemon(pokedex_number: Int, name: String)
}

pub fn main() {
  io.println(to_string(pokemon))
}

Triggering the "generate function" code action on the to_string function call will cause the language server to edit the code to add the empty function definition, including type annotations.

fn to_string(pokemon: Pokemon) -> String {
  todo
}

Programmers who write this code "top down" will find this especially convenient. Thank you to Giacomo Cavalieri, a "top down" programmer who I'm pretty sure added this entirely for himself.

Pattern match code action

The language server now suggests a code action to pattern match on a variable. For example, if you have this code:

pub fn main() {
  let result = list.first(a_list)
}

Triggering the code action on the result variable will generate the following code for you:

pub fn main() {
  let result = list.first(a_list)
  case result {
    Ok(value) -> todo
    Error(value) -> todo
  }
}

This works with values of any type, adding all the patterns you would need to exhaustively pattern match on them. It also works for function arguments as well as variables. Thank you Giacomo Cavalieri!

More fault tolerant compilation

Fault tolerant compilation is what allows the language server to still help you work with your code even when it is in an invalid state, a feature which is vital for a good experience refactoring or fixing Gleam code.

Surya Rose and Giacomo Cavalieri have improved code analysis to make the compilation of body-less case expressions and function pipelines fault tolerant. This will be extra impactful for autocompletion while writing new code. Thank you both for this!

Result wrapping hints

Gleam uses a result type for error handling instead of exceptions. At times the programmer may forget to add the Ok or Error needed in fallible functions, so Giacomo Cavalieri has made the compiler suggest where to add these to solve a type mismatch.

pub fn greet_logged_user() {
  use <- bool.guard(when: !logged_in, return: Error(Nil))
  "Hello!"
}

error: Type mismatch
  ┌─ /main.gleam:7:3
  │
7 │   "Hello!"
  │   ^^^^^^^^ Did you mean to wrap this in an `Ok`?

Expected type:

    Result(a, Nil)

Found type:

    String

Thank you Jak!

`gleam deps tree`

Gleam uses the Hex, the package manager for the BEAM ecosystem. The build tool will automatically download and compile appropriate versions of the dependencies your project needs, along with their dependencies.

The new gleam deps tree command can be used to view the relationship between all your dependencies.

$ gleam deps tree

project_a v1.0.0
├── package_b v0.52.0
└── package_c v1.2.0
    └── package_b v0.52.0

The --package option can be used to view just a portion of the dependency tree.

$ gleam deps tree --package package_c

package_c v1.2.0
└── package_b v0.52.0

And the --invert option can be used to view all paths from a package to the root of the project, which can be very useful for understanding why a particular package version was included in the project.

$ gleam deps tree --invert package_b

package_b v0.52.0
├── package_c v1.2.0
│   └── project_a v1.0.0
└── project_a v1.0.0

Thank you Ramkarthik Krishnamurthy for this new command!

HTML documentation hotkeys

Gleam can generate HTML documentation for your code when you run gleam docs build, and it will automatically generate and publish this documentation to HexDocs when publishing a package.

Sambit Sahoo has added hotkeys, making the search input be focused when cmd/ctrl + k, s or / is pressed. Thank you!

Invalid project name correction

Gleam project names have to be all lowercase letters and underscores and numbers, and not collide with any Gleam keywords. The glean new command would reject invalid names, but now it will suggest a valid name instead and ask if the programmer would like to use that instead.

$ gleam new type
We were not able to create your project as `type` is a reserved word in
Gleam.

Would you like to name your project 'type_app' instead? [y/n]:

Thank you Diemo Gebhardt for this!

Better "fill labels" code action

The language server can now fill in the labels of any function call, even when only some of the arguments are provided. For example:

import gleam/string

pub fn main() {
  string.replace("wibble")
}

Will be completed to:

import gleam/string

pub fn main() {
  string.replace("wibble", each: todo, with: todo)
}

Thank you Giacomo Cavalieri!

And the rest

And thank you to the bug fixers and error message improvers: Giacomo Cavalieri, Jiangda Wang, John Strunk, Kasim, shayan, Surya Rose, and yoshi

For full details of the many fixes and improvements they've implemented see the changelog.

A call for support

Gleam is not owned by a corporation; instead it is entirely supported by sponsors, most of which contribute between $5 and $20 USD per month, and Gleam is my sole source of income.

We have made great progress towards our goal of being able to appropriately pay the core team members, but we still have further to go. Please consider supporting the project or Giacomo Cavalieri specifically on GitHub Sponsors.

Thank you to all our sponsors! And especially our top sponsor: Lambda.

Try Gleam

This release is dedicated to the memory of my grandfather, Len Pilfold, who passed away in January.

Gleam

JavaScript source maps

Gleam gets source maps

Package-level fault tolerance

Faster string pattern matching

Record update fault tolerance

Oversized int pattern warning

Spoiling practical jokes

Hex package ownership management

Hex package manager error message improvements

Add and remove anonymous function code actions

Extract function code action improvements

Replace _ with type code action

Constant list prepending

Language server completion improvements

Tuple formatting improvement

More external code source extension support

And the rest

A call for support

Upgrading Hex security

The Hex package manager

Better Hex errors

Guard clause ergonomics

Internal types presentation

JavaScript FFI additions

Package quality publish checks

Code folding

CLI documentation improvements

Consistent configuration

Extract anonymous function

Module usage renaming

Add missing type parameter code action

String prefix language server triggering

More precise completions

Signature help type parameter names

Other language server improvements

And the rest

A call for support

Join us at Gleam Gathering

The happy holidays release 2025 🎁

External annotations for external types

Interference-based pruning for ints

Number normalisation in pattern matching analysis

More precise incorrect subject count error message

Fault tolerance

Faster equality testing

Redundant module warnings

Detached documentation warnings

Record update syntax for constants

Latest Elixir support

Outdated dependencies view

Helpful git-not-installed error message

Further code action support

Type directed autocompletion

Missing patterns order improvement

Merge case branches code action

Improved name selection in code actions

Language server rename failure notification

Improved language server diagnostic grouping

Annotate all top level definitions code action

Command line API improvements

And the rest

A call for support

Formalising external APIs

External API for Gleam data

Improved bit array exhaustiveness checking

Unused argument detection

Better meaningless opaque type error

More fault tolerance

Redundant pattern alias warning

More warnings for inefficient list use

A helpful syntax error for JavaScripters

A helpful error for Rustaceans, C#ers, and friends

A helpful syntax error for Pythonistas, Elixirists, and friends

Displaying dependency version information

hex owner transfer

Improved type displaying

Improved type naming in code actions

Tangled support

Further language server support

Replace `_` with type code action

`hex owner transfer`

Testing with `assert`

`gleam dev`