elm-pages is a hybrid Elm framework for building a single-page app that mixes pre-rendered static routes with server-rendered routes and connects seamlessly to data from an Elm backend, aimed at Elm developers building blogs, content sites, and full-stack apps.
What it is
elm-pages is a framework, published as both the npm package elm-pages and the Elm package dillonkearns/elm-pages, for building Elm single-page apps that interface with data from an Elm backend. It is a hybrid framework: routes can be server-rendered, for dynamic content driven by user-specific or request-specific data, or pre-rendered at build time, producing static HTML files hosted through a CDN. Both kinds of route can be mixed in one app. The project lives in the Elm ecosystem, is listed under Content & Publishing / Blogging & Personal Sites, and carries the topics blog, elm, elm-pages, jamstack, seo, and static-site-generator.
The concrete problem it solves is the split between sites that must be fast and crawlable and apps that must respond per request. A pure static site generator cannot serve request-specific data; a pure server-rendered app gives up the cheap CDN hosting that static HTML allows. elm-pages replaces the need to choose, letting one codebase declare some routes as build-time static output and others as server-rendered, so a site can keep its marketing pages and blog posts on a CDN while serving personalised routes from an Elm backend. It also replaces ad hoc scripting: the framework provides a command for running pure Elm scripts, and the 12.3.0 release adds a Tui module for building interactive terminal apps as elm-pages scripts, with Tui.programOrScript letting the same script run interactively in a TTY or as a plain BackendTask under CI or when its output is piped.
Key capabilities
- Hybrid routing that mixes pre-rendered routes for static HTML on a CDN with server-rendered routes for user-specific or request-specific data in one app.
elm-pages Scripts, a command for running pure Elm scripts, documented on the Scripts docs page.- The
Tui module for interactive terminal apps using TEA-style init/update/view, rendering styled text and responding to keyboard, mouse, paste, resize, and time events.
Test.PagesProgram for end-to-end tests of elm-pages routes, driving the real framework runtime through form submissions, optimistic UI, concurrent fetchers, redirects, session cookies, and error pages with simulated HTTP and custom ports.Test.Tui and Test.BackendTask for pure Elm tests of TUI programs, simulating keypresses and mouse events, resolving pending BackendTasks, and asserting on screen output.- Visual and headless test runners:
elm-pages dev serves page tests in the browser at /_tests, elm-pages test --visual steps through TUI tests in the terminal, and elm-pages test runs headlessly.
- A Compatibility Key check that raises an error when the npm package and the Elm package versions do not match.
Who uses it and how
- Elm developers building blogs and personal sites, which the topic list and the static-site-generator and seo topics point to directly.
- Teams that need CDN-hosted static pages alongside dynamic routes in a single Elm SPA, using pre-rendered routes for the former and server-rendered routes for the latter.
- Projects deploying to Netlify: the README carries a Netlify deploy status badge and a Deploy to Netlify button, and the quick start repo
dillonkearns/elm-pages-starter runs as a live site on Netlify.
- Script and CLI authors who want one Elm script to work interactively in a terminal and as a
BackendTask under CI or when piped.
- Teams wanting deterministic, in-process, browser-free end-to-end coverage of routes and TUI programs, following the approach inspired by
elm-program-test.
Getting started
Use the npm package elm-pages, or start from the quick start repo dillonkearns/elm-pages-starter, which also has a Deploy to Netlify button. To build the bundled examples from source, clone with git clone --recurse-submodules https://github.com/dillonkearns/elm-pages.git so no files are missing.
How it compares
The README names one similar tool directly: the testing API is inspired by elm-program-test, but Test.PagesProgram goes further by driving the real framework runtime through simulated HTTP and custom ports rather than testing a program in isolation. No paid products are listed among the facts, so no licence, self-hosting, or cost-model comparison can be drawn here. Within this registry the entry stands alongside general static-site tooling rather than duplicating it, because its distinguishing feature is the hybrid pre-rendered and server-rendered routing in Elm.
When to use it — and when not to
A self-hoster must keep the npm and Elm package versions in step, since a mismatched Compatibility Key produces an error, and must remember the recursive submodule clone for the examples. Routes that are server-rendered need somewhere to run the Elm backend, while pre-rendered routes need only static hosting such as a CDN. It is a poor fit for teams without Elm experience or for anyone wanting a JavaScript or TypeScript blogging stack, and the repository carries 81 open issues with the README excerpt truncated mid-sentence, so anyone evaluating it should check the docs site at elm-pages.com rather than the README alone.
