gleam-otp-development

name	gleam-otp-development
description	Guides Claude through building concurrent, fault-tolerant applications with Gleam OTP. Use when creating actors, supervision trees, or building distributed BEAM applications.

Gleam OTP Development Skill

This skill guides Claude Code through building concurrent, fault-tolerant applications with Gleam OTP.

Primary Sources

1. Gleam OTP Documentation - Complete OTP reference
2. Gleam OTP GitHub Examples - Official examples
3. Gleam OTP: Using Supervisors - Supervisor tutorial
4. Gleam OTP Design Principals - Design patterns
5. Actor Documentation - Actor API reference
6. Supervisor Documentation - Supervisor API reference

Quick Reference

Core Modules

• gleam/otp/actor - Actor processes with type-safe messaging
• gleam/otp/supervisor - Supervision trees
• gleam/otp/static_supervisor - Static supervision configuration
• gleam/otp/task - One-off concurrent tasks
• gleam/erlang/process - Low-level process operations

See: Gleam OTP Modules

Common Workflows

Creating a New OTP Application

gleam new my_otp_app
cd my_otp_app
gleam add gleam_otp gleam_erlang

Basic Actor Pattern

Consult the actor documentation for:

• Creating actors: Actor - start
• Message handling: Actor - Next
• Calling actors: Actor - call

Supervision Tree Setup

For supervision patterns, see:

• Supervisor - start
• Supervisor - add
• Supervisor - worker

Example structure:

Application Supervisor
├── Database Pool Supervisor
│   ├── Connection 1
│   ├── Connection 2
│   └── Connection N
├── Web Server Supervisor
│   ├── HTTP Listener
│   └── Request Handlers
└── Background Job Supervisor
    └── Worker Pool

See: Gleam OTP: Using Supervisors

One-Off Tasks

For concurrent one-off operations: Task Module

Alternative with more features: Taskle Library

Design Patterns

GenServer-Style Actor

// State, Message types, start function, handle function

See complete examples: Actor Examples

Worker Pool

For worker pool implementation patterns: Gleam OTP Design Principals

Event Manager

For pub/sub patterns, consult:

• Process - send
• Custom event manager implementations

Registry Pattern

For process registration and discovery: Process - register

Supervision Strategies

Choose the right restart strategy:

OneForOne

Restart only the failed child. Use for: Independent workers

OneForAll

Restart all children if one fails. Use for: Tightly coupled processes

RestForOne

Restart failed child and all started after it. Use for: Dependent process chains

See: Supervisor Strategies

Testing OTP Applications

Testing Actors

import gleam/otp/actor

pub fn actor_test() {
  let assert Ok(actor.Started(subject, _)) = start_my_actor()
  let result = actor.call(subject, waiting: 100, sending: fn(s) { MyMessage(s) })
  let assert expected = result
}

Testing Supervisors

Test supervision behavior:

• Child starts correctly
• Child restarts on crash
• Supervisor respects max restart limits

See: Testing Guide

Monitoring and Debugging

Erlang Observer

Monitor your OTP application:

iex -S mix  # For Elixir projects
erl  # For Erlang projects

Then: :observer.start()

Process Monitoring

Use process monitoring functions: Process - monitor

Logging

Integrate logging: Palabres - OTP Logging

Common Anti-Patterns

Refer to: OTP Anti-Patterns

Key anti-patterns to avoid:

• Processes as state (use variables instead)
• Unsupervised processes
• Large messages between processes
• Using processes for code organization

Libraries for OTP Development

Core

• gleam_otp - OTP framework
• gleam_erlang - Erlang runtime

Extended

• taskle - Elixir-like Task functionality
• glixir - Safe Gleam-Elixir OTP interop

Utilities

• palabres - Logging for OTP apps

Hot Code Reloading

Gleam supports Erlang's hot code reloading, but type safety isn't guaranteed during upgrades.

See: Gleam FAQ - Hot Code Reloading

Deployment Considerations

Release Building

Use Gleam's Erlang release functionality:

gleam export erlang-shipment

See: Deploying to Fly.io

Configuration

Use environment variables: Envoy Library

Clustering

For distributed Erlang clusters, consult:

• Gleam Erlang - Node
• Erlang distribution documentation

Example Applications

Find complete OTP application examples:

• Gleam OTP Examples
• Community projects using OTP

When to Use OTP

✅ Use OTP when you need:

• Long-running stateful services
• Fault tolerance and automatic restarts
• Concurrent independent operations
• Process isolation

❌ Don't use OTP for:

• Simple pure computations
• Organizing code (use modules)
• Holding simple state (use variables)

See: OTP Patterns

---

Remember: OTP is powerful but has specific use cases. Consult official documentation for current patterns and best practices.