Lesson 2 — Vera, how the gem works

The dispatch deck chassis ships with the Vera gem already installed and configured — it’s in the Gemfile, its Stimulus controllers are registered, its CSS is linked, and its JavaScript modules are pinned in the importmap. You don’t need to add anything to start using it.

What you do need is a sense of what’s actually there. The gem is the bridge between Rails-and-Phlex on one side and MapLibre-and- JavaScript on the other. Understanding what each part does, and where the seams between them are, will make the rest of this tutorial significantly easier to follow. This lesson walks through Vera’s contribution to the chassis — what it provides, what it doesn’t, and what its API surface looks like.

No code yet. We’ll start writing components in Lesson 3.

What MapLibre is

Before we look at Vera, a brief tour of what’s underneath it.

MapLibre GL JS is an open-source web map library. It started in 2020 as a community fork of Mapbox GL JS — when Mapbox went proprietary at version 2, the open-source community forked the last MIT-licensed version and continued developing it as MapLibre. Today it’s a mature, actively maintained library used by serious mapping teams.

Three things matter about MapLibre for our purposes.

It’s vector-tile-native. Older libraries like Leaflet were designed around raster tiles — pre-rendered PNG images of map imagery, which the browser stitched together into a viewport. Vector tiles are different. The server sends compact binary descriptions of features (roads, water, places), and the browser renders them with WebGL. The result is sharper at all zoom levels, supports runtime styling (recolour the map without asking the server), and is dramatically faster for dense data.

It’s declaratively styled. A MapLibre map is configured by a JSON style document — sources, layers, paint properties, and filter expressions. You don’t write imperative code that adds and removes elements. You declare a configuration, and MapLibre renders accordingly. This shape fits beautifully with how Phlex components work.

It’s WebGL-based. Performance is closer to a video game than to a typical web library. Half a million points on the screen at once is unremarkable; Leaflet starts struggling at a few thousand. This matters for Module 7 when we scale up the dataset.

The downside is that MapLibre’s API is large. The configuration JSON has dozens of layer types, hundreds of paint and layout properties, and a substantial expressions language for runtime styling. Writing it directly from a Stimulus controller is verbose, error-prone, and scatters configuration across files.

That’s where Vera comes in.

What Vera is

Vera wraps MapLibre with a Phlex DSL. The same JSON configuration you’d write by hand is generated from Phlex component code that reads the way Rails developers expect their code to read.

A typical piece of MapLibre configuration looks something like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "sources": {
    "depots": {
      "type": "geojson",
      "data": "/depots.geojson"
    }
  },
  "layers": [
    {
      "id": "depots-circles",
      "type": "circle",
      "source": "depots",
      "paint": {
        "circle-radius": 6,
        "circle-color": "#0066cc",
        "circle-stroke-width": 1,
        "circle-stroke-color": "#ffffff"
      }
    }
  ]
}

The same thing in Vera’s DSL is shaped like:

1
2
3
4
5
6

m.source :depots, type: :geojson, url: "/depots.geojson"
m.layer  :depots, id: :circles,   type: :circle,
         paint: { circle_radius: 6,
                  circle_color: "#0066cc",
                  circle_stroke_width: 1,
                  circle_stroke_color: "#ffffff" }

You can clearly see the correspondance between the raw json and the ruby equivalent here. The key thing is that instead of creating and managing many stimulus controller files, you’ll be working with pure ruby code in custom components. This makes composing new maps a much easier prospect.

You’ll see in the next lesson how you can literally create a map with a single line of ruby code - can’t get much easier than that!

What’s in the gem

Vera has four major contributions to a Rails application:

1. The Phlex map components. Vera::Map is the main one. It accepts a configuration via a block-based DSL with helpers for sources, layers, popups, controls, and the drawing toolkit. There are specialised components like Vera::Map::Marker for declaring markers inline, and the gem composes well with your own Phlex components (e.g., a domain-specific JobMarker that extends Vera::Map::Marker).

2. Stimulus controllers. Three controllers are shipped with the gem and registered in the chassis. vera--map manages the MapLibre instance for a map element — initialising it, applying the configuration, handling events, broadcasting state changes. vera--actions is a small controller that connects buttons and links to common map actions (fly to a point, fit a bounding box, open a popup) without you writing any custom Stimulus. vera--draw activates Geoman drawing tools when the page calls for them.

3. Action helpers. A method called action_attrs on Vera::Map generates the data attributes needed to wire up buttons, links, or any element to the vera--actions controller. A typical use: a button on a list of locations that, when clicked, flies the map to that location and drops a marker. You write the data attributes via action_attrs; Stimulus does the rest. We’ll see this pattern starting in Module 5.

4. JavaScript module pins. The gem ships ESM modules (vera/install, vera/map_controller, etc.) that are pinned in the importmap. This is what lets the chassis load Vera’s JavaScript through Rails 8’s importmap system without a build step. There’s also a one-line registration helper — registerVeraControllers(application) — that makes wiring the controllers into your Stimulus application trivial.

What Vera does NOT do

Worth being explicit about the boundaries. Vera is not a complete GIS library. It doesn’t:

• Provide spatial database integration. That’s PostGIS’s job. The gem doesn’t know about your models, your geometry columns, or your queries. The Rails application is responsible for producing GeoJSON; the gem renders it on a map.

• Generate map tiles. Tile servers are a separate concern. Most of the tutorial uses Carto’s positron-styled vector tiles for the base map — they’re free, fast, and well-styled for data overlays. Module 7 introduces serving custom vector tiles from PostGIS.

• Wrap every MapLibre feature. The gem’s DSL covers the common cases — sources, layers, paint properties, popups, controls, drawing — but MapLibre has features the DSL doesn’t expose. When you need to reach those, the gem provides escape hatches: the extra: option on layers and markers passes through arbitrary properties, and the vera--map Stimulus outlet exposes the underlying MapLibre map object for cases where raw access is genuinely required. We’ll see all of this in Module 5.

• Replace your understanding of MapLibre. If you go deep into custom paint expressions, layer effects, or tile sources, you end up reading MapLibre’s documentation. The gem hides complexity for the common cases; it doesn’t change what’s underneath.

How it’s wired into the chassis

The chassis you cloned has Vera fully integrated already. Three specific places to know about:

Gemfile has the gem itself:

1

gem "vera", git: "https://github.com/your-org/vera", tag: "v0.1.0"

(Once Vera is published to RubyGems, this becomes the simpler gem "vera", "~> 0.1" form. For the moment it’s a Git reference.)

config/importmap.rb has the JavaScript pins:

1
2
3
4
5

pin "maplibre-gl",                   to: "https://esm.run/maplibre-gl"
pin "@geoman-io/maplibre-geoman-free", to: "https://esm.run/@geoman-io/maplibre-geoman-free"
pin "vera/install",                  to: "vera/install.js"
pin "vera/map_controller",           to: "vera/map_controller.js"
pin "vera/actions_controller",       to: "vera/actions_controller.js"

The first two pins fetch MapLibre and Geoman from esm.run (a CDN that converts npm packages to ESM modules). The remaining pins are Vera’s own modules, which the gem serves via Rails’s asset pipeline. The reader doesn’t need to think about this; it just works.

app/javascript/controllers/index.js registers Vera’s Stimulus controllers:

1
2
3
4
5
6

import { application } from "controllers/application"
import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
eagerLoadControllersFrom("controllers", application)

import { registerVeraControllers } from "vera/install"
registerVeraControllers(application)

The first three lines are the standard Rails 8 Stimulus loading pattern. The last two register Vera’s controllers — vera--map, vera--actions, vera--draw — alongside whatever controllers you’ve put in app/javascript/controllers/.

app/views/layouts/application.html.erb loads the necessary stylesheets:

1
2

<link href="https://unpkg.com/maplibre-gl/dist/maplibre-gl.css" rel="stylesheet">
<link href="https://cdn.jsdelivr.net/npm/@geoman-io/maplibre-geoman-free/dist/maplibre-geoman.css" rel="stylesheet">

The MapLibre stylesheet is required for any page that renders a map. The Geoman stylesheet is only needed for pages that use the drawing toolkit, but it’s small — a couple of kilobytes gzipped — and shipping it globally simplifies the layout.

That’s all the wiring. From the developer’s perspective, using Vera in a page is just rendering Vera::Map from a Phlex component or directly in an ERB view.

The DSL surface in one diagram

A Vera::Map is configured via a block. Inside the block, you have access to a small set of DSL methods:

1
2
3
4
5
6
7
8

Vera::Map.new(id: "lab", centre: [-25, 134], zoom: 4) do |m|
  m.source :name, type: :geojson, url: "/path"
  m.layer  :name, type: :circle,  paint: { ... }
  m.marker [-33.86, 151.21], popup: "Sydney"
  m.popup  [-33.86, 151.21], html: "<p>...</p>"
  m.draw   modes: %i[polygon edit]
  m.control :navigation, position: :top_left
end

The methods you’ll see most are:

• m.source — declares a data source for the map
• m.layer — adds a styled layer rendering data from a source
• m.marker — adds a single marker at a coordinate
• m.popup — adds a free-floating popup
• m.draw — enables the drawing toolkit
• m.control — adds a built-in control (navigation, scale, attribution)

We’ll meet each of these in turn. Sources and layers come up in Module 4. Popups and markers in Module 5. Drawing in Module 8. Controls in Lesson 5 of this module.

A note on the underscore-vs-kebab convention

You’ll notice the DSL uses snake_case for paint property names — circle_radius, circle_color — even though MapLibre’s JSON uses kebab-case (circle-radius, circle-color). The gem translates between them.

This is one of those small details that matters because it removes a class of subtle bugs. MapLibre is unforgiving about property names: a typo doesn’t raise an error, the property is just silently ignored. By accepting symbol keys with snake_case (which is the Ruby convention), the gem catches typos at the component level — circle_radious raises an error in a way that circle-radious in JSON wouldn’t.

The same translation happens for layer types, source types, and other config keys. You write Ruby; the gem produces correct MapLibre JSON.

The two languages your application speaks

Stepping back, an application using Vera ends up speaking two languages.

On the server: Ruby, Rails, ActiveRecord, PostGIS. You write controllers that produce GeoJSON from spatial queries. You write Phlex components that declare maps with sources and layers. The thinking is database-shaped and component-shaped — exactly the rhythm Rails developers are used to.

In the browser: MapLibre renders the map and handles the interactions. The Stimulus controllers Vera ships translate the configuration the server produced into MapLibre calls, listen for events, and update state. You don’t write any of this JavaScript yourself for the common cases.

The boundary between the two is the data the controller emits — a JSON config the gem generates from the Phlex component, plus the data attributes for the action helpers. Crossing that boundary in either direction is rare in a well-designed application. Most chapters in this tutorial don’t cross it at all.

This is the architectural shape that makes spatial work feel like Rails work, instead of feeling like JavaScript work that happens to live in a Rails app.

1

Stimulus.application.controllers.map(c => c.identifier)

Where this leaves us

You now understand:

• What MapLibre is and what makes it different from Leaflet
• What Vera contributes — Phlex components, Stimulus controllers, action helpers, importmap pins
• What’s wired up in the chassis already (Gemfile, importmap, controllers, stylesheets)
• What the DSL looks like in shape
• The boundary between server and browser, and why most chapters don’t cross it

Lesson 3 is where we render a real map. We’ll add a /lab route, a controller, and the first Phlex view that declares a Vera::Map. Australia will appear on your screen.