When I first started working at Mapbox this past summer, I was poking around in our (800+!) public github repositories and a familiar domain name caught my attention.  geojson.io, a long-time staple of my web mapping toolkit, was staring back at me, longing for some love, attention, and maintenance. This is a brief narrative of how we gave geojson.io a little TLC over the past few months, and set it up for easier maintainability moving forward.

I have used it for years, with about 5 different use cases depending on what I’m doing. I find it particularly helpful for teaching. There’s no better way to explain what geojson is to new web mappers than to draw a polygon on a map and have well-formatted data appear instantly in a code editor.  

Curiosity piqued. I guess I never looked into it that seriously, but I always assumed geojson.io was a personal project of Tom MacWright, a former Mapbox Engineer who has a prolific presence in our company’s open code along with all things web mapping, javascript, and dataviz. Even in 2022, many years after his departure, googling for help with Mapbox tools is certain to land you on a public github thread where Tom is leading a spirited technical discussion in the open, hearing all sides but weighing in with strong and well-reasoned opinions. Tom and others like him have shown me the merits of coding in the open over the years, values I’ve applied in every technical job I’ve worked at along with personal projects. He has since moved on to working on Placemark.io, a successor project to geojson.io for spatial data management.  

A Steady Trickle of Issues

Geojson.io still had issues popping up on github from time to time. Those who went to take a look at the repository were greeted with a foreboding message:

This message was added to the readme in 2018, but the 75 or so new issues added to the repo over the next 4 years showed that spatial devs were still using it, and still seeking  improvements and bugfixes. Geojson.io is simple, and that’s the point. It’s not a GIS tool with 100 widgets and buttons. It does just a few things and does them well. It has the lowest of learning curves, doesn’t require a lot of documentation, and just about everyone working with spatial data will find some value in it quickly. You can use it to draw and edit spatial data, manually edit properties, and convert to different formats. You can use it to quickly preview the output data from your data pipeline and make sure everything is in order.  

Figuring Out the Lift

Before digging in on anything else, I started looking into what it would take to get geojson.io to use Mapbox GL JS, the library that revolutionized web mapping with vector tiles, incremental zooming, smooth pitching and rotation, and smooth 60fps WebGL rendering (and so much more, these are just the easiest to list). Mapbox GL JS was first released in 2015 (goodness, has it been that long?), a couple of years after the first commit on geojson.io. Geojson.io made use of mapbox.js, a leaflet-based frontend library that represents the older paradigm of web mapping, usually with SVG vector data rendered atop a tiled raster basemap.  

Here’s an issue from 2017 where a user asks about bringing in GL JS:

This issue really outlines the need for a style editor for Mapbox GL JS layers, which we now have in the form of Mapbox Studio. This line spoke to me: “But I'm sure other folks are also interested in getting geojson.io on the GL JS train, and if you're interested in trying it out, I'm open to most sorts of contributions!”. Challenge accepted, 5 years on!

I spent a few eventings poking around the codebase to get an idea of the lift required to bring in Mapbox GL JS. I immediately bumped into issues with the local development environment, as building the javascript bundles depended on older versions of packages that didn’t play well with modern versions of node.js. This would have stopped many would-be contributors dead in their tracks, Mapbox employees or otherwise, so simplifying the development environment also became a high priority to eliminate barriers to working on the codebase. 

I made progress quickly on a personal github fork, sharing screengrabs and a working github-pages site with people who I thought might be interested. From Wednesday, July 20th:

The map rendering and drawing bits are well-isolated in the code. When data is imported, or loaded from localstorage, it is stored in a centralized state object and events are dispatched to update things like the table, code editor and map.  Likewise, when drawing geometries or editing via the popups, the map can dispatch events to update the centrally-stored data. Migrating just meant swapping out each call to Mapbox.js with its equivalent in Mapbox GL JS, trading in things like L.geoJSON() for map.addSource() and map.addLayer().  

Drawing features would prove a bit trickier, as Mapbox GL Draw doesn’t work in exactly the same way as Leaflet Draw. Getting feature parity here would require some custom buttons and an explicit “editing” state that doesn’t exist out of the box in Mapbox GL Draw.

Changing the basemap also took some additional work, as there is no concept of a basemap in Mapbox GL JS. A map’s style can include all of the layers we would consider a basemap, but custom or app-specific layers can be inserted anywhere in the stack.  This meant adding some code to listen for style changes and then re-insert the working dataset’s sources and layers.

Over the course of a couple of months, I was able to get my branch into stable feature parity for display, editing, and layer switching.  Simultaneously, I started to see alignment with reviving this project and some of my developer community-building goals, and thought this initiative doesn’t need to be a strictly extra-curricular.

Shipping It

A working branch is a great start, but it soon became time to think about what it would actually take to bring these changes in. I started an internal slack channel to start building a braintrust of coworkers who could opine on various features, review code, and otherwise share a bit in this undertaking. I excel at being a squeaky wheel, and would constantly drop links to the staging site, screenshots, and questions, always seeking to strike up dialogue about the merits of this or that feature. After a couple of weeks of testing and improvements, it was ready to go.

Here’s the Pull Request that finally brought in mapboxgl: https://github.com/mapbox/geojson.io/pull/703

You’ll notice right away that there’s a huge regression introduced: the removal of authentication. Auth in geojson.io allows for reading and writing to github repos and gists, a popular feature with some users, but one that has been fraught with issues over the years and required granting github privileges to a third party. We thought it best to remove it altogether and revisit it at a later date when we can put the appropriate thinking into it and support the entire feature end-to-end. Most of the code for auth is still in place, we just hid the UI for the time being.

After the changes went live, we saw some activity on twitter, and even a blog post that gave us a nudge to update the changelog. Some issues started popping up on github identifying regressions that had slipped through the cracks, and there’s been a steady slew of small PRs following the release that address these.  One example was the implementation of simplestyle-spec. As the name suggests, it’s a spec that allows for style properties to be defined in geojson parameters for things like color, stroke, opacity, etc.  I wasn’t clear if it was being used at all, and figured if anyone missed it they would speak up. (They did, and now it’s *mostly back in place).  

We also added some nice-to–have features:

• Collapsible brackets in the code editor
• Additional Core Styles (basemaps)
• Switching between globe and mercator projections
• Persistence of basemap and projection settings  across sessions
• A copy button in the code editor

Is this my job? Yes it is.

I’m leading our new Developer Relations program at Mapbox, with a mission to inspire and equip everyone who builds with Mapbox tools. I’ve divided the work into three pillars: Developer Content, Developer Community, and Developer Tools. Tools are a big one for me, as there are so many in the spatial dev’s toolkit that don’t get enough attention, documentation, or support.  I want whoever ends up working with me in Developer Relations to support and maintain real-world developer tools in addition to the tutorials and quick-n-dirty demos they may put together when working on content.  

As an open source project, I also hope geojson.io can play a role in our developer community-building efforts. I can’t vouch for every open repo at Mapbox, but for now you can rest assured that geojson.io development is “un-paused”.  Someone on my team will be watching when you open an issue, and we’re going to provide a more active forum to encourage contributions and feedback from the community. 

Plans for the Future

It’s meant a lot to me to have the opportunity to work on geojson.io. It is a bit of a perfect storm of having the required skillset (web mapping and javascript development, with a little bit of product management), the bandwidth, and a community-facing remit. The core functionality, UI, and architecture are mostly the same, a lot of the recent changes have been refactoring the build process and adding some polish, bells and whistles to the existing featureset. I’ve dived deep and grokked the codebase, made it easier to set up the development environment, and am now in a good position to steward the project moving forward. Please take a look at the issue queue, there are plenty of “good starter task” issues that we could use your help on!

I fully acknowledge that the internal slack channel and braintrust I described above are not the most inclusive and community-focused. Though the issues and PRs for geojson.io are public, a lot of the discourse around it is not. I’d like to change that, and will be announcing a new public forum for Mapbox Developers at our December 1st BUILD with Mapbox event. I’ll also be hosting a breakout session about Developer Relations, where I’ll outline my goals for our DevRel program and share some recent work around Content, Community, and Tooling. I hope to see you there!

Thanks for reading! May geojson.io live for another decade and beyond!