When starting a new application, one of the biggest decisions you'll make isn't just what to build—but where to build it. Should it be a mobile app? A desktop tool? A web application? Your choice of platform will shape everything that follows, from the programming languages you use to the frameworks that define your workflow.
Want to build a native application for Mac? You will most likely be working within Xcode and write Swift. If you are targeting mobile, you will likely use Swift and Xcode for iOS and Kotlin/Android Studio for Android. Alternatively, you may opt for a cross-platform framework like React Native."
For web applications, the range of available technologies is much broader. Instead of being locked into a single toolset, you can choose based on ergonomics, performance, or simply personal preference.
For example, if you learned PHP in school, you might feel right at home building web apps with a framework like Laravel. Or, if you prefer JavaScript, frameworks like Next.js or SvelteKit offer a seamless developer experience.
However, regardless of the stack you choose, all web applications must follow the same fundamental structure:
A web application fundamentally consists of two parts: a back-end server, which processes requests via an HTTP server, and a front-end (also referred to as "client"), which provides interactivity using JavaScript.
These days, when we talk about building the "full stack" of our application, the trend is to adopt a Javascript framework, for the simple reason that Javascript is the only language that allows us to have client-side interactivity (without having to resort to WASM).
If you are not comfortable building a server in Javascript/Typescript, you could opt to delegate the server part all together, by using a Back-end-as-a-Service ("BaaS") like Supabase or PocketBase.
However, not everyone wants to write JavaScript. For those looking for an alternative approach, tools like HTMX allow you to generate HTML fragments and swap them out in your pages, freeing you from the need to write Javascript, and allowing you to choose your preferred language on the server (e.g. Python).
But what if you wanted the best of both worlds? To get type safety while avoiding the hell that is Typescript tooling, and cover the entire stack with a single language? Enter ✨ Gleam ✨ — a delightful new language that can do just that!
Why Gleam?
If you want a quick intro to Gleam, I invite you to read my previous article on the subject.
Gleam's pitch is simple: a functional language for type-safe applications that can run anywhere. It manages to do that by running on both the Erlang virtual machine ("the BEAM", named after its creators), and on Javascript runtimes.
The fact that Gleam is strongly-typed means that we could, in the context of a web application:
Define types for what exists in our database (back-end), e.g. user information, and the functions to retrieve that data and provide it to the client;
Re-use these types to define how this information could be rendered on the page (front-end).
This is great ergonomics, for the simple reason that duplication of types between the client and the server is the bane of productivity for small teams (or solo developers) writing web applications, and should be avoided at all costs. For example, anyone who's ever built a web application with a Flask back-end (Python) and a React front-end (Javascript) has been bitten by one of the two choices available to them:
Foregoing types altogether, which makes runtime errors much more frequent; or
Duplicating types between fron-end and back-end, which means everything has to be kept in sync.
This website is built statically using Gleam as well! See it on Github here
A very simplified version of a web app written in Gleam would look a little something like this:
// shared.gleam
pub type User {
User(id: String, name: String)
}
pub type Post {
Post(id: String, body: String, user: User)
}
fn render_posts_page(posts: List(Post)) -> HtmlResponse {
todo
}// server.gleam
fn get_posts_for_user(db: Connection, user_id: String) -> List(shared.Post) {
todo
}
fn handle_request(req: Request, db: Connection, user_id: String) -> Response {
// --> This will redirect to the log in page if the user is not logged
use req, logged_user <- check_auth(req, user_id, db)
let posts = get_posts_for_user(db, logged_user.id)
shared.render_posts_page(posts)
}// client.gleam
fn render_posts_page(posts: List(shared.Post)) -> HtmlWithJavascript {
todo
}Here, our server takes care of authenticating the user, loading data from our database, and finally respond with HTML that contains our page. This page will however need to be "hydrated" with Javascript, which is to say that the Javascript on the page will have to attach the interactive elements to the page once it has been rendered, which is the job of our client-side code.
This rendering strategy is called Server-side rendering ("SSR"), where our server and client both "collaborate" in serving the interactive application to our users. Other strategies include Static pre-rendering, where all of the pages are built at build-time and the server is simply serving those built HTML files, and Client-side rendering, where the server renders a mostly empty HTML shell, and the client (the browser) is responsible for rendering the rest of our app inside that shell.
Websites built using Static pre-rendering are usually called "static sites", while applications rendered client-side are called "Single Page Applications" (or "SPA")
Components of a full-stack Gleam app
To built a full-stack web application in Gleam, you will need a set of three Gleam modules, i.e.
One for the HTTP server which will serve requests, compiled to Erlang;
One for the client-side application, to allow for client-side interactivity, compiled to Javascript; and
One for our shared types and functions, which will get compiled to both targets.
A simplified representation of our folder structure would look something like this:
.
├── client
│  ├── src
│  └── gleam.toml
├── server
│  ├── src
│  └── gleam.toml
└── shared
├── src
└── gleam.tomlThe need for separate Gleam projects stems from the fact that Gleam generally works better with a single entry point and a single compilation target.
Gleam supports local dependencies quite well, as we only have to write the following
in the gleam.toml file of both client and server:
[dependencies]
shared = { path = "../shared" }Generating HTML
The generation of HTML is both a client and a server problem. On the server, we need to generate our first HTML page, and on the client, we need to render any new HTML resulting from our interactions with the page.
Gleam has an amazing library called lustre which is a batteries-included web application framework that compiles to both the BEAM and Javascript, making it a prime choice for our use case.
lustre does everything:
Static websites (like this one);
SPAs;
Hydration of SSR apps; and
even Server components, bringing you fully server-rendered app, with updates streaming via WebSockets, Ã la Phoenix LiveView.
The simplest example of a SPA built using lustre is a counter with two buttons, one to increment the counter by one, and the other to decrement it by one. The code is given in the docs and provided below
import gleam/int
import lustre
import lustre/element.{text, type Element}
import lustre/element/html.{div, button, p}
import lustre/event.{on_click}
pub type Model = Int
fn init(_flags) -> Model {
0
}
type Msg {
Incr
Decr
}
fn update(model: Model, msg: Msg) -> Model {
case msg {
Incr -> model + 1
Decr -> model - 1
}
}
fn view(model: Model) -> Element(Msg) {
let count = int.to_string(model)
div([], [
button([on_click(Incr)], [text(" + ")]),
p([], [text(count)]),
button([on_click(Decr)], [text(" - ")])
])
}
pub fn main() -> Nil {
let app = lustre.simple(init, update, view)
let assert Ok(_) = lustre.start(app, "#app", Nil)
Nil
}
And here it is, with some styling added:
Quite cool isn't it? Embedding small apps like these using
lustreis actually quite simple, but a topic for another day 😊
The way it works is quite simple:
modeldescribes the state of our app. Normally, we would define a custom type, but here it's just anInt.The
initfunction returns the initialize model (here0).The
updatefunction updates the model based on a message.The
viewfunction returns HTML from our model.
We interact with our app by sending messages to the update function, which will update the model, and then the view function will update our HTML.
This is a usual set up for a SPA, but for our SSR app, we will have to move some of the elements above into our shared project. As a matter of fact, the easiest way to work is to move everything but the main function to shared, with the main function importing everything it needs to compile our Javascript application.
The HTTP server
For a full stack application, we need an HTTP server. The server's role is simple: receive HTTP requests and send HTTP responses (with some processing in between, admittedly).
Although a relatively new language, Gleam already has web framework library named Wisp that uses the Mist web server, and provides improved ergonomics for routing, middleware, working with cookies, etc.
Here is the "Hello World" example from the Wisp repository:
import gleam/erlang/process
import mist
import wisp/wisp_mist
import gleam/string_tree
import wisp.{type Request, type Response}
pub fn middleware(
req: wisp.Request,
handle_request: fn(wisp.Request) -> wisp.Response,
) -> wisp.Response {
let req = wisp.method_override(req)
use <- wisp.log_request(req)
use <- wisp.rescue_crashes
use req <- wisp.handle_head(req)
handle_request(req)
}
pub fn handle_request(req: Request) -> Response {
use _req <- middleware(req)
let body = string_tree.from_string("<h1>Hello, Joe!</h1>")
wisp.html_response(body, 200)
}
pub fn main() {
wisp.configure_logger()
let secret_key_base = wisp.random_string(64)
let assert Ok(_) =
wisp_mist.handler(router.handle_request, secret_key_base)
|> mist.new
|> mist.port(8000)
|> mist.start_http
process.sleep_forever()
}One thing that separates Wisp from other lightweight web frameworks like those found in Python (e.g. Flask and FastAPI) is that Gleam does not have macros or meta-programming, and we therefore cannot rely on something like the @route decorator to define routes.
Is that a negative? Not necessarily. While it will lead to code that is more verbose, it's still all functions all the way down, and things remain simple that way.
After all, we can still build composable apps like what you would do using blueprints in Flask, except it's all based on functions calling other functions.
Wisp only has two canonical constructs:
Request handlers, i.e. functions that take in a request and return a response; and
Middleware, i.e. functions that process every request before passing it to its handler.
Middleware is built by composing processing functions and passing the request along, until it is ready for the handler. Those types of functions make extensive use of the use keyword in Gleam, which is a lovely feature that can be hard to grasp at first (and will be the topic of an upcoming post).
Because you will be handling your routing with no help from a meta-framework, it is up to you to define how you structure your routes. For my simple apps, I usually go with the following:
Page routes, i.e. routes that render HTML to serve to the browser;
API routes, i.e. routes that will handle requests that are data-focused and interact with my database; and
Routes to handle user authentication.
Because our server will generally need to return data from some kind of persistent storage, we have to set up a database.
The database
Because Gleam has no meta-programming, interacting with a database is generally not done via an Object-Relational Mapper ("ORM"), but rather via raw SQL. You will also need to write specific decoders to coerce SQL outputs into proper Gleam types.
Below is a simple example of how one would query data from an SQLite database using the sqlight library.
import gleam/dynamic/decode
import sqlight
pub fn main() {
use conn <- sqlight.with_connection("my_db.db")
let cat_decoder = {
use name <- decode.field(0, decode.string)
use age <- decode.field(1, decode.int)
decode.success(#(name, age))
}
let sql = "
SELECT name, age
FROM cats
"
let assert Ok(result) =
sqlight.query(sql, on: conn, with: [], expecting: cat_decoder)
}This might send a shiver down your spine, considering how verbose it is! But we can do better, thanks to the closest thing we have to meta-programming:
✨ Code generation ✨
One of my favorite Gleam tools is this lovely library called squirrel that takes care of generating all of the necessary types, decoders and query functions based on our SQL files. With squirrel, I can write .sql files, get syntax highlighting for them, run them against my database when I need to run migration, etc., without a dependency with my app's runtime.
Here is an example of a query, and the resulting file generated by squirrel:
-- get_users.sql
SELECT *
FROM users// sql.gleam
import gleam/dynamic/decode
import pog
pub type GetUsersRow {
GetUsersRow(id: String, name: String, email: String, email_verified: Bool)
}
pub fn get_users(db) {
let decoder = {
use id <- decode.field(0, decode.string)
use name <- decode.field(1, decode.string)
use email <- decode.field(2, decode.string)
use email_verified <- decode.field(3, decode.bool)
decode.success(GetUsersRow(id:, name:, email:, email_verified:))
}
let query = "SELECT *
FROM users"
pog.query(query)
|> pog.returning(decoder)
|> pog.execute(db)
}squirrel only works with PostgreSQL, so we will have to deploy an instance for our application (see Deployment)
Authentication
For authentication, I usually keep it simple and use Google as an OAuth provider, and give that as the only way to authenticate into the app.
This tutorial provides the building blocks to implementing the OAuth flow. Wisp has signed cookies, so you can simply store whatever token you use to check your user's authentication in there.
Deployment
When I first started exploring web applications, one of the biggest challenges I faced was figuring out how to deploy them to the internet. Even if I was the only intended user, I still wanted the flexibility to access my app from anywhere, including my phone when I was away from home. Running the app on localhost just wasn’t going to cut it.
I briefly explored serverless solutions, like Vercel and Netlify, who have generous free tiers to get you started and some niceties like "push to deploy". However, configuration can be tricky, and making a mistake can end up costing you dearly.
Following the words of levelsio and DHH, I ended up looking into how I could deploy my apps on a Virtual Private Server ("VPS"). Of course, the solution is Docker, but there is a tool out there to make this entire a process: Coolify.
Coolify is a self-hosted Platform-as-a-Service ("PaaS") tool with a long list of features, included but not limited to:
Push-to-deploy
Free SSL certificates
Preview deployments
Database back-ups
One-click deploy of multiple self-hosted services (incl. observability solutions like Posthog)
To get set up with Coolify, I've used the Coolify docs as well as this comprehensive tutorial from SyntaxFM.
Deploying a PostgreSQL database on Coolify
To deploy a PostgreSQL instance to Coolify, you can simply create a new resource to your project and select PostgreSQL.
In there, there is an option to make your database accessible through the Internet, which means you will be access that database when working locally. This removes the need for setting up a local instance, allowing you to iterate faster.
Deploying our app
To deploy our app on our VPS with Coolify, we have to first build a Docker image for it.
Here is the example of a Dockerfile I would use to deploy an app using the three-project structure we introduced above:
ARG GLEAM_VERSION=v1.8.0
FROM ghcr.io/gleam-lang/gleam:${GLEAM_VERSION}-erlang-alpine AS builder
# Add project code
COPY ./shared /build/shared
COPY ./client /build/client
COPY ./server /build/server
# Compile the client code to Javascript and place the
# bundle into the static asset directory served by the
# server
RUN cd /build/client \
&& gleam run -m lustre/dev build app --outdir=../server/priv/static
# Compile the server code to Erlang
RUN cd /build/server \
&& gleam export erlang-shipment
# Start from a clean slate
FROM ghcr.io/gleam-lang/gleam:${GLEAM_VERSION}-erlang-alpine
# Copy the compiled server code from the builder stage
COPY --from=builder /build/server/build/erlang-shipment /app
# Run the server
WORKDIR /app
ENTRYPOINT ["/app/entrypoint.sh"]
CMD ["run"]Conclusion
This is only scratching the surface, but I hope this introduction to the capabilities of Gleam when it comes to building web applications will get you motivated in trying it out and building your own stuff.
With its minimal syntax, and strong compile-time guarantees (via its type system), Gleam makes building robust and scalable applications simpler. While I, myself, am only on the beginning of that journey, I do believe that the ethos of Gleam will lead to application that are simpler to reason about, while still keeping a full understanding of the underlying technology. This is something that can sometimes be difficult to keep a grasp on when dealing with Javascript meta-frameworks, since those tend to abstract away a lot of the complexity from you.
In the future, expect to see more on my experience in building actual production-grade applications using these methods.