How to Use PMTiles with the Esri JavaScript API (ArcGIS Maps SDK)

The other day, a customer dropped a question in our inbox that made us pause: "Hey, can we use PMTiles with Esri’s JavaScript API?"

Our first thought? Honestly, probably not. A quick scan of the ArcGIS Maps SDK for JavaScript documentation didn’t show any native support for the PMTiles format. It seemed like a technical dead end.

But "probably not" isn’t really our style. We love a good challenge, so we rolled up our sleeves, fired up our code editors, and started experimenting. And you know what? It is possible. With a clever little workaround, you can get the slick, serverless power of PMTiles lighting up your Esri maps.

This post is the story of how we cracked it—and how you can, too.

Why We Love PMTiles (And You Should Too)

To understand the workaround we used with the Esri Javascript API, it helps to first appreciate the core problem PMTiles was built to solve: managing millions of tiny map files in cloud storage. Uploading and synchronizing a massive directory of individual tiles is slow and incredibly difficult to manage.

PMTiles elegantly solves that headache by consolidating everything into a single, cloud-optimized file.

Here’s how it works: a browser first reads the small header of the PMTiles file. This header acts as an internal directory, telling the browser the exact byte-range location for every tile inside the larger file. From then on, the browser uses efficient HTTP Range Requests to ask the cloud storage, "Hey, give me the tile located at position X, Y, and Z."

The result is a truly serverless format. You get the simplicity of managing a single file with the power to serve it directly from any object storage, drastically simplifying deployment and lowering hosting costs.

Making Your Own PMTiles, Supercharged

So, how do you get your own data into this powerful format? We believe that part should be simple, too. We built our own PMTiles generator to transform massive geographic datasets into a web-ready file with just three lines of code.

Our generator uses a distributed architecture to process your data in parallel for maximum speed, even on small hardware. As a quick test, we converted the entire TIGER railroad dataset—all 112,000 line-strings. The result?

• Time to generate: Under 3.5 minutes
• Total cost to generate: $0.42

This makes generating large-scale, web-ready PMTiles not just possible, but incredibly cheap and fast.

The Plot Twist: What the Esri API Expects

So, if PMTiles is so great, what’s the catch? The hiccup comes from how Esri’s VectorTileLayer expects to find its data.

Out of the box, it’s looking for a classic tile server URL structure, something like .../Z/X/Y (zoom level, column, row). PMTiles, with its single-file, range-request approach, doesn’t speak that language. It’s a classic case of a mature technology that hasn’t yet caught up with the efficiencies of modern formats.

To get them to talk to each other, we need to build a small translator. In this case, it’s a lightweight service that sits in the middle, fetches data from the PMTiles file using its native strengths, and then serves it up in the classic Z/X/Y format that the ArcGIS SDK loves.

See It To Believe It

Talk is cheap, right? Here’s a quick video showing what our PMTiles look like, rendered beautifully inside an Esri JavaScript API map.

Get Your Hands Dirty: Your Turn to Build!

Ready to stop reading and start coding? We’ve made it incredibly easy for you to get this up and running on your own. No complex setups, we promise.

Step 1: Create Your PMTiles File

Here’s a Jupyter notebook hosted in Wherobots that walks through the process, from grabbing geographic data to creating your own optimized .pmtiles file. ➡️ Click here to access the Jupyter notebook

Step 2: Set Up the Tile Server

Next, let’s start the "translator" service we discussed. We’ve open-sourced a lightweight tile server on our GitHub repository. Clone the repo, follow a few simple setup steps, and you’ll be serving your PMTiles to the Esri SDK in minutes. ➡️ Get the code on GitHub

Dive in, play around with the code, and see for yourself how powerful this combination can be. We can’t wait to see what you build! If you have questions or ideas, feel free to open a new discussion thread on GitHub. Better yet, if you’d like to help improve the project, we welcome all contributions to the repo.

Get started with Wherobots

Try Now