Module 1 — Why this tutorial exists
4 lessons · framing · no code yet Before we open a terminal, we’ll establish what we’re building, who this is written for, and what to expect along the way.
Before we start
Most Rails developers reach mapping the same way. You need to put markers on a map, you Google “Rails maps,” and you find a Leaflet tutorial from 2017. You glue it together, it works, and that’s that — until you need to do something more interesting. Display polygons. Filter what’s shown by URL parameters. Make popups that integrate with Turbo Frames. Save shapes the user draws. Show real-time positions for a fleet of vehicles.
Each step out of “marker on a map” pulls you deeper into JavaScript. The
Leaflet object becomes a bag of addLayer and removeLayer calls. The
glue Stimulus controller grows. You start writing helpers in JS to talk
to Rails and helpers in Rails to format data for JS. The Rails parts of
your app are clean Phlex components and idiomatic ActiveRecord, and the
mapping parts are an island of imperative JavaScript that nobody
including you really wants to touch.
This tutorial is for the moment you decide that island has gone on long enough.
By the end of it, you’ll have built a national field-service dispatch application — Vera Dispatch Manager — with a half-million-row spatial database, an interactive map of Australia, role-aware UI for three distinct user types, and a real-time view of vehicles moving across the country. None of that involves a single line of JavaScript you wrote yourself. The maps are declared in Phlex components. The interactions are configured via Stimulus controllers that ship with the gem. The queries are PostGIS one-liners. The architecture is normal Rails.
It’s also a tutorial about GIS, and that’s worth saying explicitly. We build with the mapping library and the Phlex DSL, but the harder material — and the more transferable — is the GIS underneath. How PostGIS thinks about geometry. What spatial indexes actually contain. When to use a polygon, when to use a buffer. How to query a million rows in space. These ideas don’t go away if you swap MapLibre for Leaflet, or Phlex for ERB, or even Rails for something else. They’re the substrate of any serious spatial application.
You’ll come out the other side knowing both: how to build modern, declarative, Hotwire-friendly maps in Rails, and how to think about spatial data the way GIS practitioners do.
That’s a lot to promise. The next four lessons explain what’s coming in more detail, who this tutorial is written for, what you’ll know by the end, and the three user roles that shape the application throughout. None of it requires opening a terminal — that starts in Module 2.