Tom MacWright

Map Codeflow

For quite a while now, I’ve been working on the new Mapbox Studio, a visual map styling tool. It’s based on Mapbox GL and writes styles in the GL Style Spec, a dialect of JSON.

What we’ve been working on is a visual tool: you can import and export JSON, but unlike previous products, the focus is more on a user interface than it is on a tricked-out CodeMirror-based code editor. This is indicative of some deeper changes.

Vector tiles split data processing and rendering

Mapbox GL being in-browser makes it possible to build a much simpler style editor. CartoCSS, our previous styling langage, compiled down to Mapnik XML in a rather slow build step. And then the styles needed a Mapnik install to run.

Mapnik does many jobs: it parses geospatial data formats, projects that data, applies fancy styles and anti-aliasing, and then creates tiny and efficient PNG & JPG files.

In stark contrast, the world of Mapbox Vector Tiles and Mapbox GL detaches the rendering from the data processing: one tool turns geodata into tiles, another tool turns tiles into images.


While the MBTiles & CartoCSS standards have had time to grow, and now have quite a few implementations, vector tiles are admittedly bleeding edge, and the projects we’re starting to release are some of the first examples of what they can do.

From building the new Mapbox Studio first as a code interface, and then as a UI, I’m entirely convinced that visual is the way forward. We can make a new promise to people: that they will no longer run into silly syntax errors, or have three abstractions to debug simultaneously. There’ll no longer be a language that’s a bit like CSS, but not exactly: the GL Style Spec opens us up to a whole new universe of tooling that works extremely well with JSON - something that would never happen with a custom syntax. And with no parse errors in-between changes, we can smoothly transition between differerent variations of a style and save every change in an undo/redo history.

The code flow

What’s really exciting (besides, of course the new Mapbox Studio) is that Mapbox GL makes it simpler to build powerful software with maps. There should be lots of good options, in many different styles.

So: the mapbox-gl-codeflow-example shows how you develop Mapbox GL styles in code. In around 60 lines of simple JavaScript, it runs a little gulp command that props up a server, reloads a page on changes, and moves around files. It’s like TileMill, without the UI: as we eventually learned, a lot of people technical enough to write code are also very partial to their text editors, so you can use Sublime/vim/emacs/Atom or whatever you’d like.

There’s one bonus feature, inspired by a few people’s comments about JSON being a rather strict language. The example includes converters for YAML, toml, and JSON5, so you can use a terse, comment-supporting language as input, if you’d like.

A layer in YAML

  - id: 'background'
    type: 'background'
      'background-color': '#f00'


  id = 'background'
  type = 'background'
    background-color = '#f0f'


  id: 'background',
  type: 'background',
  paint: {
    'background-color': '#ff0'

For even more power, it also supports JavaScript applications as input, so you can actually author styles in JavaScript and it’ll run them: so you can use JavaScript’s wide range of libraries and native support for variables and operations. In my example, I’m using chroma-js as a subsitute for CartoCSS’s color operations.


I think a lot about errors: it seems like error-handling is one of the most important parts of any development environment.

So this example also includes error handling: for syntax errors in JavaScript, semantic errors in stylesheets, and parse errors in JSON, it shows the error in a nicely-formatted browser window. It’s inspired by React Native’s awesome error-display style.

Just an example

This is just one example of a tool for a GL style development workflow: there are many other ways to do it, in other languages with different wheelies. The whole of the code is shorter than most Gulp build scripts.

Stay tuned for Mapbox Studio, and check out the codeflow example on GitHub.