fist - v1.4.0

Fist User Guide 👊

This guide provides practical examples for using the Fist router in your Gleam applications.

Table of Contents

  1. Core Concepts & Behavior - How the router works, path normalization, and precedence.
  2. Basic Routing - Defining simple static and dynamic routes.
  3. Advanced Patterns - Middleware, Context, and Custom Return Types.
  4. Integration & Deployment - Using with Mist and Serving Static Files.

Basic Routing

Static routes are exact string matches. They always take priority over dynamic routes.

import fist
import gleam/http/response

fn home_handler(_, _, _) {
  response.new(200) |> response.set_body("Welcome Home!")
}

pub fn main() {
  let router =
    fist.new()
    |> fist.get("/", to: home_handler)
    |> fist.get("/about", to: fn(_, _, _) {
      response.new(200) |> response.set_body("About Us")
    })
}

Dynamic Parameters

Dynamic routes use segments starting with : to capture values. These values are passed to your handler in the params dictionary.

import fist
import gleam/dict
import gleam/result
import gleam/http/response

fn user_handler(_req, _ctx, params) {
  // Extract the "id" parameter
  let id = dict.get(params, "id") |> result.unwrap("unknown")

  response.new(200)
  |> response.set_body("Viewing user: " <> id)
}

pub fn main() {
  let router =
    fist.new()
    |> fist.get("/users/:id", to: user_handler)
}

Route Metadata & Documentation

Fist allows you to attach descriptions to routes. This is useful for generating documentation automatically.

import fist

let router =
  fist.new()
  |> fist.get("/users", to: list_users)
  |> fist.describe("Returns a list of all users")

  |> fist.post("/users", to: create_user)
  |> fist.describe("Creates a new user")

Introspection

You can inspect the registered routes programmatically:

import gleam/io

pub fn print_routes(router) {
  fist.inspect(router)
  |> list.each(fn(route) {
    io.println(route.method <> " " <> route.path <> " - " <> route.description)
  })
}
// Output:
// GET /users - Returns a list of all users
// POST /users - Creates a new user

Continue reading:

✨ Search Document