--- title: "How to Use PMTiles with the Esri JavaScript API (ArcGIS Maps SDK)" url: "https://wherobots.com/blog/use-pmtiles-esri-javascript-api-arcgis/" description: "Learn how to use PMTiles with the Esri JavaScript API. Follow this step-by-step guide to serve PMTiles in ArcGIS Maps SDK using a lightweight tile server" published: "2025-10-27" modified: "2026-10-19" --- # 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?”** Key takeaways - The ArcGIS Maps SDK for JavaScript has no native PMTiles support, but Wherobots shows a workaround. A lightweight translator service reads PMTiles via HTTP range requests and serves classic Z/X/Y tiles to Esri VectorTileLayer. - PMTiles packs an entire tile pyramid into one cloud-optimized file. The browser reads a small header directory, then fetches individual tiles with byte-range requests from object storage, with no tile server farm or millions of tiny files to sync. - Wherobots distributed PMTiles generator turns large datasets into a web-ready file in three lines of code. Converting the entire TIGER railroad dataset (112,000 line-strings) took under 3.5 minutes and cost $0.42. - A Jupyter notebook walks through generating the file in Wherobots; an open-source tile server on GitHub is the translator you clone to serve those tiles into an Esri map. 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](https://wherobots.com/blog/vector-tile-generation-pmtiles-wherobots/) 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](https://cloud.wherobots.com/notebooks/t7mrr85vblxkf4/generate-pmtiles-for-web-maps-in-wherobots) ### **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](https://github.com/wherobots/pmtiles-esri-tile-layer) 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 [START BUILDING](https://login.cloud.wherobots.com/sign-up) ## Frequently Asked Questions ### Does the Esri JavaScript API support PMTiles natively? No. ArcGIS Maps SDK VectorTileLayer expects a classic /Z/X/Y tile URL. PMTiles does not speak that protocol, so you need a small translator service in the middle. ### How does the PMTiles-plus-Esri workaround work? A lightweight tile server fetches tiles from the PMTiles file using HTTP range requests, then exposes them in the Z/X/Y structure VectorTileLayer expects. Wherobots open-sourced that server on GitHub. ### How fast can Wherobots generate PMTiles? In the post’s test, the full TIGER railroad dataset of 112,000 line-strings became a PMTiles file in under 3.5 minutes for $0.42. It used a distributed generator that runs in three lines of code. ### Where do I get the notebook and tile server? The post links a Wherobots Jupyter notebook for generating PMTiles and a GitHub repository for the open-source tile server that fronts Esri maps. Questions and contributions go to that repo.