Gleam Getting Started - Stop Fighting the Type System, Start Building Shit

Why Gleam Installation Sucks (And How to Fix It)

Let me save you some time: Gleam installation is straightforward once you know what breaks. But the official docs assume you understand BEAM, have never installed conflicting language runtimes, and definitely haven't spent the last hour wondering why gleam --version returns "command not found."

Here's what actually works, with the gotchas nobody mentions.

The Erlang Dependency That Will Fuck You

Gleam needs Erlang/OTP to run. Not optional. Not "recommended." Required.

The problem? If you've ever installed Elixir, Phoenix, or any other BEAM language, you probably have multiple Erlang versions fighting each other. This will bite you later when packages mysteriously fail to compile.

Check what you already have:

erl -version
## Should show Erlang (SMP,ASYNC_THREADS) (BEAM) emulator version X.X

If that command fails, you need Erlang. If it shows version 23 or older, you need to upgrade. Gleam fails with Erlang versions older than 24. Trust me on this one - I spent two hours debugging compiler errors before realizing my Ubuntu had ancient Erlang.

Just Use Package Managers

macOS: Use Homebrew. Period.

brew install gleam

If you already have Erlang from Elixir or whatever, uninstall everything first:

brew uninstall erlang elixir gleam
brew install gleam

Linux: Ubuntu's packages work fine:

sudo apt update && sudo apt install erlang gleam

If that doesn't work for some reason, grab the binary from GitHub releases and drop it in /usr/local/bin/.

Windows: Use Scoop:

scoop install erlang gleam

Everyone else: Use asdf version manager with the gleam plugin. Works on everything and handles multiple versions nicely.

What Actually Breaks During Installation

"gleam: command not found" - Your PATH is fucked. On macOS, run echo $PATH and make sure you see /opt/homebrew/bin (M1/M2) or /usr/local/bin (Intel). On Linux, /usr/local/bin should be there. I spent 20 minutes debugging this when I had an old ~/.zshrc that was overriding my PATH.

True story: I once installed Gleam, then spent an hour wondering why it wasn't working. Turns out I had an old alias in my .bashrc that was redirecting gleam to some Python script from 2019. Check for weird aliases first.

Fix it permanently:

## macOS (add to ~/.zshrc or ~/.bash_profile)
export PATH=\"/opt/homebrew/bin:$PATH\"

## Linux (add to ~/.bashrc)
export PATH=\"/usr/local/bin:$PATH\"

Multiple Erlang versions fighting - This happens if you've installed Elixir, RabbitMQ, or other BEAM tools. Gleam fails with version conflicts. Check what you have:

which erl
ls -la $(which erl)
erl -version  # Try to use a recent version

If you see version conflicts, nuke everything and start fresh (takes about 5 minutes):

## macOS
brew uninstall --ignore-dependencies erlang elixir gleam
brew install gleam

## Linux - remove all Erlang packages and reinstall
sudo apt remove erlang* esl-erlang
## Then reinstall from scratch - this breaks RabbitMQ if you have it

Permission errors on Linux - Don't sudo random shit. If you need sudo to install, that's fine, but never run sudo gleam commands. I learned this the hard way when sudo gleam new created a project owned by root and spent 20 minutes fixing file permissions.

Even better: I once fixed "permission denied" by running sudo gleam run and then wondered why my compiled binaries wouldn't run normally. Turns out sudo creates cache files owned by root in ~/.gleam. Had to sudo rm -rf ~/.gleam and start over.

M1/M2 Mac weirdness - If you're getting \"Exec format error\" or \"bad CPU type in executable\", you're running Intel binaries on Apple Silicon. This will waste 30 minutes of your life. Fix it:

arch -arm64 brew install gleam

Your First Project (That Actually Does Something)

Skip the \"Hello World\" bullshit. We're building a CLI tool that fetches data from an API, because that's what you'll actually do in real projects.

gleam new api_client
cd api_client

This creates the standard structure:

• `gleam.toml` - Project config (like package.json but less insane)
• src/api_client.gleam - Your main code
• test/api_client_test.gleam - Tests that might actually pass

Adding Dependencies Without Npm Hell

Gleam's package management is what npm should have been. Add HTTP handling:

gleam add gleam_http gleam_httpc gleam_json

This updates gleam.toml with exact versions. No lockfile conflicts, no rm -rf node_modules, no "works on my machine" dependency resolution bullshit.

Write Code That Compiles (First Try)

Replace src/api_client.gleam with something useful:

import gleam/http/request
import gleam/httpc
import gleam/io
import gleam/json
import gleam/result

pub fn main() {
  case fetch_user_data(1) {
    Ok(user) -> io.println(\"User: \" <> user)
    Error(msg) -> io.println(\"Failed: \" <> msg)
  }
}

fn fetch_user_data(user_id: Int) -> Result(String, String) {
  let url = \"https://jsonplaceholder.typicode.com/users/\" <> int.to_string(user_id)

  case request.to(url) {
    Error(_) -> Error(\"Invalid URL\")
    Ok(req) -> case httpc.send(req) {
      Error(_) -> Error(\"Network request failed\")
      Ok(response) -> case response.status {
        200 -> Ok(response.body)
        _ -> Error(\"API returned status \" <> int.to_string(response.status))
      }
    }
  }
}

Wait, that won't compile. Gleam doesn't have int.to_string in scope. Imports are explicit - this trips people up.

I wasted 10 minutes staring at some error about "Unknown variable int" thinking my installation was broken. Nope, just forgot the import:

import gleam/int  // <-- Always forget this

Run It and Watch It Work

gleam run

If you get compile errors, read them. Gleam's error messages are actually helpful, unlike TypeScript's "Type 'string' is not assignable to type 'never'" nonsense.

Common first-project fuckups:

• Forgetting imports (add them)
• Typos in function names (Gleam catches these)
• Wrong types (the compiler tells you exactly what's wrong)

Editor Setup That Doesn't Suck

Install the VS Code Gleam extension. It actually works - real-time errors, go-to-definition, autocomplete that doesn't suggest random garbage.

I tried using vim with the Gleam plugin first because I'm stubborn. Spent two days fighting LSP configurations before giving up and switching to VS Code. Sometimes the easy path is the right path.

For Vim users who learn from my mistakes:

Plug 'gleam-lang/gleam.vim'

The Language Server Protocol support is solid. Unlike Python where the LSP suggests 47 different imports for json, Gleam actually knows what types things are.

I've built enough web apps to know that most of them work fine until they don't. Last week I had to debug a Node.js app that was randomly returning null instead of user data because someone forgot to await a Promise three levels deep. Gleam's approach to web development is refreshingly different: the type system catches the stupid shit that usually breaks in production.

The Web Framework Situation (It's Actually Good)

Unlike JavaScript where you have 47 different ways to build a web app, Gleam has clear, focused choices:

Wisp - The main web framework. Built by Louis (Gleam's creator), so it's probably not going anywhere. Think Express.js but the compiler catches your mistakes.

Lustre - Frontend framework that compiles to JavaScript. Like React but without the `useState` nightmare and surprise re-renders.

Mist - HTTP server that sits under Wisp. You don't touch this directly unless you're doing something weird.

Building a Real Web Application

I'll show you how to build a todo application that demonstrates practical Gleam web development patterns.

Project Setup

gleam new todo_web
cd todo_web

## Add web development dependencies - versions change fast, use whatever's latest
gleam add wisp mist lustre gleam_http gleam_json envoy

## Add development dependencies
gleam add --dev gleescript

Application Structure

Create the following file structure:

src/
├── todo_web.gleam          # Main entry point
├── todo_web/
│   ├── web.gleam           # Global middleware and types
│   ├── router.gleam        # Request routing
│   ├── models/
│   │   └── todo.gleam      # Data models
│   └── pages/
│       ├── layout.gleam    # HTML layout
│       └── home.gleam      # Home page

Core Application Code

src/todo_web.gleam - Application entry point:

import gleam/erlang/process
import mist
import wisp
import wisp/wisp_mist
import todo_web/router
import todo_web/web.{Context}
import envoy

pub fn main() {
  wisp.configure_logger()

  // Load environment variables
  let secret_key = case envoy.get(\"SECRET_KEY\") {
    Ok(key) -> key
    Error(_) -> \"dev-secret-key-change-in-production\"
  }

  let port = case envoy.get(\"PORT\") {
    Ok(port_str) -> case int.parse(port_str) {
      Ok(port) -> port
      Error(_) -> 8000
    }
    Error(_) -> 8000
  }

  // Initialize application context
  let ctx = Context(
    static_directory: static_directory(),
    todos: []
  )

  // Start web server
  let handler = router.handle_request(_, ctx)

  let assert Ok(_) =
    wisp_mist.handler(handler, secret_key)
    |> mist.new
    |> mist.port(port)
    |> mist.start_http

  process.sleep_forever()
}

fn static_directory() -> String {
  let assert Ok(priv_dir) = wisp.priv_directory(\"todo_web\")
  priv_dir <> \"/static\"
}

src/todo_web/web.gleam - Shared types and middleware:

import wisp
import todo_web/models/todo.{type Todo}

pub type Context {
  Context(static_directory: String, todos: List(Todo))
}

pub fn middleware(
  req: wisp.Request,
  ctx: Context,
  handle_request: fn(wisp.Request) -> wisp.Response,
) -> wisp.Response {
  let req = wisp.method_override(req)
  use <- wisp.serve_static(req, under: \"/static\", from: ctx.static_directory)
  use <- wisp.log_request(req)
  use <- wisp.rescue_crashes
  use req <- wisp.handle_head(req)

  handle_request(req)
}

src/todo_web/models/todo.gleam - Data models:

import gleam/option.{type Option}
import wisp

pub type Todo {
  Todo(id: String, title: String, completed: Bool)
}

pub fn new_todo(title: String) -> Todo {
  Todo(id: wisp.random_string(16), title: title, completed: False)
}

pub fn toggle_completed(todo: Todo) -> Todo {
  Todo(..todo, completed: !todo.completed)
}

Request Routing

src/todo_web/router.gleam:

import wisp.{type Request, type Response}
import todo_web/web.{type Context, Context}
import todo_web/pages/layout
import todo_web/pages/home
import gleam/http
import gleam/list
import gleam/result
import lustre/element

pub fn handle_request(req: Request, ctx: Context) -> Response {
  use req <- web.middleware(req, ctx)

  case wisp.path_segments(req) {
    // Home page
    [] -> {
      [home.view(ctx.todos)]
      |> layout.render
      |> element.to_document_string_builder
      |> wisp.html_response(200)
    }

    // Create todo
    [\"todos\"] -> {
      use <- wisp.require_method(req, http.Post)
      create_todo(req, ctx)
    }

    // Toggle todo completion
    [\"todos\", id, \"toggle\"] -> {
      use <- wisp.require_method(req, http.Post)
      toggle_todo(req, ctx, id)
    }

    // 404 for unmatched routes
    _ -> wisp.not_found()
  }
}

fn create_todo(req: Request, ctx: Context) -> Response {
  use form <- wisp.require_form(req)

  case list.key_find(form.values, \"title\") {
    Ok(title) -> {
      // This crashed our staging server when someone pasted War and Peace into the todo field
      // Turns out when you don't validate input, some joker will paste 50,000 characters and break everything
      case validate_todo_title(title) {
        Ok(valid_title) -> {
          let new_todo = todo.new_todo(valid_title)
          let updated_todos = [new_todo, ..ctx.todos]
          // In a real app, save to database here
          wisp.redirect(\"/\")
        }
        Error(reason) -> wisp.bad_request() // Should show reason to user
      }
    }
    Error(_) -> wisp.bad_request()
  }
}

fn validate_todo_title(title: String) -> Result(String, String) {
  case string.length(title) {
    0 -> Error(\"Title cannot be empty\")
    n if n > 500 -> Error(\"Title too long (max 500 characters)\")
    _ -> Ok(title)
  }
}

fn toggle_todo(req: Request, ctx: Context, todo_id: String) -> Response {
  let updated_todos =
    list.map(ctx.todos, fn(t) {
      case t.id == todo_id {
        True -> todo.toggle_completed(t)
        False -> t
      }
    })

  // In a real app, save to database here
  wisp.redirect(\"/\")
}

HTML Templates with Lustre

src/todo_web/pages/layout.gleam:

import lustre/element.{type Element}
import lustre/element/html
import lustre/attribute

pub fn render(content: List(Element(t))) -> Element(t) {
  html.html([], [
    html.head([], [
      html.meta([attribute.charset(\"utf-8\")]),
      html.meta([
        attribute.name(\"viewport\"),
        attribute.attribute(\"content\", \"width=device-width, initial-scale=1\")
      ]),
      html.title([], \"Gleam Todo App\"),
      html.style([], [element.text(css())])
    ]),
    html.body([], content)
  ])
}

fn css() -> String {
  \"
  body { font-family: system-ui; max-width: 600px; margin: 0 auto; padding: 20px; }
  .todo-form { margin-bottom: 20px; }
  .todo-input { padding: 10px; font-size: 16px; width: 70%; }
  .todo-button { padding: 10px 20px; font-size: 16px; }
  .todo-item { display: flex; align-items: center; padding: 10px; border-bottom: 1px solid #eee; }
  .todo-completed { text-decoration: line-through; opacity: 0.6; }
  .todo-toggle { margin-right: 10px; }
  \"
}

src/todo_web/pages/home.gleam:

import lustre/element.{type Element, text}
import lustre/element/html
import lustre/attribute
import todo_web/models/todo.{type Todo}
import gleam/list

pub fn view(todos: List(Todo)) -> Element(t) {
  html.div([], [
    html.h1([], [text(\"Gleam Todo App\")]),

    // Todo form
    html.form([
      attribute.class(\"todo-form\"),
      attribute.method(\"post\"),
      attribute.action(\"/todos\")
    ], [
      html.input([
        attribute.class(\"todo-input\"),
        attribute.name(\"title\"),
        attribute.placeholder(\"What needs to be done?\"),
        attribute.required(True)
      ]),
      html.button([
        attribute.class(\"todo-button\"),
        attribute.type_(\"submit\")
      ], [text(\"Add Todo\")])
    ]),

    // Todo list
    html.div([], list.map(todos, todo_item))
  ])
}

fn todo_item(todo: Todo) -> Element(t) {
  let item_class = case todo.completed {
    True -> \"todo-item todo-completed\"
    False -> \"todo-item\"
  }

  html.div([attribute.class(item_class)], [
    html.form([
      attribute.method(\"post\"),
      attribute.action(\"/todos/\" <> todo.id <> \"/toggle\")
    ], [
      html.button([
        attribute.class(\"todo-toggle\"),
        attribute.type_(\"submit\")
      ], [text(case todo.completed {
        True -> \"✓\"
        False -> \"○\"
      })])
    ]),
    html.span([], [text(todo.title)])
  ])
}

Running Your Web Application

## Development mode - takes about 3 seconds to compile and start
gleam run

## Visit localhost:8000 in your browser
## Add todos, mark them complete, see type-safe HTML generation
## If it's not working, check the terminal - Gleam error messages are actually helpful

Database Integration

For real applications, you'll want persistent storage. The Gleam ecosystem provides several options:

SQLite with Sqlight:

gleam add sqlight

PostgreSQL with Pog:

gleam add pog

Using existing Erlang/Elixir libraries:
Many Erlang database drivers work with Gleam, though you'll need to write type-safe wrappers.

Deployment Considerations

Unlike PHP or Node.js, BEAM applications are designed for long-running processes. Your Gleam web app:

• Starts once and handles millions of requests
• Manages memory automatically with per-process heaps
• Handles failures gracefully through supervision trees
• Scales horizontally across multiple CPU cores and servers

I'm not going to repeat the entire deployment guide here - check the official Gleam deployment docs for Docker, BEAM releases, and cloud deployment.

BEAM apps are different beasts - they handle thousands of concurrent users without breaking a sweat, unlike Node.js which falls over if someone sneezes wrong. Your app will keep running even when individual parts crash, because BEAM was designed by people who understood that shit breaks in production.

Stop Fucking Around with Tutorials, Build Real Shit

Tutorial hell is real. Stop doing toy projects and build things that matter:

Pattern Matching Isn't Optional: This is how you handle data in Gleam. Master it or stay confused forever:

// Lists
case my_list {
  [] -> "empty list"
  [first] -> "one item: " <> first
  [first, ..rest] -> "first: " <> first <> ", rest: " <> length_description(rest)
}

// Custom types
case user_result {
  Ok(User(name: name, age: age)) if age >= 18 -> "Adult: " <> name
  Ok(User(name: name, age: _)) -> "Minor: " <> name
  Error(NotFound) -> "User not found"
  Error(InvalidData(reason)) -> "Invalid: " <> reason
}

Result Type Handling: Learn to chain operations without nested conditionals:

get_user_id(request)
|> result.try(fetch_user_from_db)
|> result.try(validate_permissions)
|> result.map(render_user_profile)
|> result.unwrap_or(show_error_page)

List Processing: Master the standard library functions:

users
|> list.filter(fn(user) { user.age >= 18 })
|> list.map(fn(user) { user.name })
|> list.sort(string.compare)
|> list.take(10)

Projects That Actually Teach You Gleam

Skip the calculator tutorials. Build things that solve real problems:

Start with CLI tools

Log Parser: Take your nginx/apache logs and extract useful shit. I built one last month - parsing timestamps is 80% of the work because Apache logs have 47 different date formats depending on your config.

Config File Validator: Every project has config files that break. I spent two hours debugging why staging wouldn't start, turned out someone forgot a comma in JSON. Build a validator, save yourself that pain.

File Processor: Automate boring data transformation. CSV files are the devil - every export has slightly different formatting, encoding issues, missing columns. Handle the edge cases or debug weird Unicode errors at 2am.

Then build some APIs

REST API for Something Real: Pick a domain you actually understand. Don't build another todo API - build something for inventory management, booking systems, whatever you know. Domain knowledge matters more than tech stack.

Authentication Service: Everyone needs this and everyone underestimates it. JWT sounds simple until you deal with token expiration, refresh tokens, and logout edge cases. I spent a day debugging why users stayed logged in after logout (client-side storage isn't magical).

File Upload Handler: "Just accept the file and save it" they said. Then someone uploads a 500MB image disguised as a .txt file and your server dies. File uploads are where security goes to die.

Eventually try harder stuff

Real-time Chat: Learn the actor model properly. WebSockets seem simple until you deal with disconnections, message ordering, and scaling to multiple servers. I built a chat system that worked great with 5 users, then completely fell apart when we hit 50 concurrent connections.

Background Job Processor: Handle async work correctly. Job queues are deceptively complex - you need retries, dead letter queues, priority handling, and monitoring. I once built a "simple" job queue that turned into a 2000-line monster because I didn't plan for failure cases.

Essential Packages to Learn

As the ecosystem matures, focus on these stable, well-documented packages:

Start with Wisp for web development - it's the standard framework and actually works well. Lustre for frontend if you need it, Mist handles the HTTP server layer but you don't touch it directly.

For databases, Sqlight and Pog are your options. Gleam JSON for JSON parsing - you'll need this for any web API work.

Other stuff worth knowing: Envoy for environment variables, Gleam HTTP for HTTP types, Gleam Erlang when you need to call Erlang functions directly. There's probably other stuff but that covers the basics.

Learning Resources Beyond This Guide

The official Language Tour is actually good - interactive, shows real examples, doesn't waste your time. The Writing Gleam guide covers project setup and development workflow. Package docs are on the main site.

For community help, Discord is where the action is. More helpful than Stack Overflow for Gleam questions. Gleam Weekly newsletter keeps you updated without spam.

Exercism has a solid Gleam track with mentors who know their shit. The online Playground works for quick experiments when you can't be bothered to create a project.

Understanding BEAM Concepts

As you get comfortable with Gleam syntax, start learning BEAM-specific concepts:

Actor Model: Every function runs in a lightweight process. Processes communicate through messages, not shared memory. This is different from threads.

OTP (Open Telecom Platform): Battle-tested patterns for building fault-tolerant systems. I don't fully understand all of this yet, but the main concepts are:

• GenServers: Stateful processes with defined interfaces
• Supervisors: Monitor and restart failed processes
• Applications: Bundle related functionality

Distribution: BEAM applications can supposedly run across multiple machines transparently. Haven't tried this myself but it's what people say.

These concepts differentiate BEAM languages from other platforms and explain why companies like WhatsApp and Discord choose them for high-scale systems.

Transitioning to Production

Once you're building real applications, focus on production readiness:

Error Handling Strategy: Design error recovery at the application level, not just function level. Use supervisor trees to restart failed components.

Monitoring and Observability: Learn Observer for development debugging and Recon for production troubleshooting.

Performance Characteristics: Understand that BEAM optimizes for latency and fault tolerance, not raw CPU throughput. Design accordingly.

Deployment Patterns: Practice with Docker containers first, then learn BEAM releases for production deployments.

Contributing to the Ecosystem

As a new language, Gleam benefits from community contributions:

Documentation: Improve package documentation, write tutorials, create examples.

Packages: Build wrapper libraries for useful Erlang/JavaScript libraries.

Bug Reports: File detailed issues when you encounter problems.

Teaching: Share your learning experience through blog posts or talks.

The Gleam community is welcoming to newcomers and values different perspectives on language design and ergonomics.

Long-term Learning Path

Master the syntax first - few weeks. Build simple apps - another month.

Then learn BEAM/OTP patterns, which is honestly the harder part. The functional programming concepts transfer to Elixir, Haskell, F# if you decide to explore other languages later.

Advanced stuff like distributed systems and performance optimization comes later, maybe after 6 months when you actually understand what you're doing.

When You Get Stuck

Compile Errors: Read them carefully - Gleam's error messages are designed to be helpful. They often suggest fixes or alternatives.

Runtime Issues: Use io.debug() liberally to understand program flow. The type system prevents many runtime errors, so when they occur, it's usually logic or external system issues.

Performance Problems: Profile first, optimize second. BEAM's performance characteristics are different from other platforms - understand them before making assumptions.

Missing Features: Check if someone has already built what you need. The community is responsive to requests for new packages or features.

Remember that Gleam is designed to make correct programs easy to write. If something feels difficult or error-prone, there's usually a more idiomatic approach. Ask the community for guidance - the Discord server is particularly helpful for learning best practices.