Recently, while working on WebGIS projects, I often ran into the problem of large GeoJSON files freezing during loading. Previously, the common default approach was either to use tools like tippecanoe to pre-slice data into vector tiles, or to start a backend service for dynamic processing. One takes up storage, the other takes up server resources, and neither is hassle-free. In the end, I discovered that Mapbox has open-sourced a library called geojson-vt, which can slice GeoJSON into vector tiles on demand purely on the front end. In the official demo, U.S. ZIP code data at 100 MB and 5.4 million points can also render smoothly in the browser. Today, I will show you this library.

Introduction to geojson-vt

geojson-vt is an efficient JavaScript library open-sourced by Mapbox. Its core function is to dynamically slice GeoJSON data into vector tiles in the browser, enabling large-scale spatial data rendering and interaction in a "serverless" scenario. The library was open-sourced in 2015, and its author is Vladimir Agafonkin, who is also the author of Leaflet. It was originally written to support the GeoJSON data source of Mapbox GL JS, and later it also became usable in Leaflet, OpenLayers, d3, and Node.js on the server side. For those who are not yet familiar with GeoJSON itself, you can first read my previous article "GIS Tutorial: What Is GeoJSON". The GeoJSON standard has also been evolving in recent years. For example, I previously shared the OGC's JSON-FG extension in "GeoJSON Releases a New Standard: JSON-FG Is Here!".

The tiles produced by slicing are the JSON version of the vector tile specification (MVT). To make rendering and interaction faster, each zoom level is simplified, retaining only the details that match the precision of that level. Shapes are simplified, and polygons and polylines that are too small are filtered out. For the evolution of vector tile formats, you can refer to my previous article "Big News! Is MVT's Successor Here? MapLibre Officially Releases the MLT Vector Tile Format", in which I introduced that MapLibre launched a new-generation MLT format after MVT.

Core Working Principle

In principle, geojson-vt does index once, tile on demand, with several internal modules working together.

  • convert: converts GeoJSON into an internal format, while performing Web Mercator projection, unifying it into the tile coordinate space.
  • simplify: uses the Douglas-Peucker algorithm to simplify geometries by zoom level; the lower the level, the more aggressive the simplification.
  • clip: clips geometries by tile boundaries to ensure each feature correctly falls into the corresponding tile.
  • tile/transform: organizes the processed geometries into tile objects that conform to the specification, then performs coordinate conversion.

The key is tiling on demand. During initialization, only the index up to indexMaxZoom (default level 5) is built. Higher levels are not precomputed; instead, a tile is cut only when the front end requests a certain z/x/y. Therefore, initialization is very fast, and subsequent tile requests basically return in milliseconds. When data is updated, there is no need to republish tiles; just pull the GeoJSON again and rebuild the index.

Quick Start

Install:

npm install geojson-vt

Basic usage:

import GeoJSONVT from 'geojson-vt';

const tileIndex = new GeoJSONVT(geoJSON);

// Request a tile
const features = tileIndex.getTile(z, x, y).features;

// View generated tile coordinates
console.log(tileIndex.tileCoords); // [{z: 0, x: 0, y: 0}, ...]

getTile returns null outside the data extent. If you pursue zero-copy, you can use getTileRaw to directly get the stored data, which returns a flat [x, y, x, y, ...] typed array, one array per ring.

You can also include the CDN directly in the browser:

<script src="https://unpkg.com/geojson-vt/geojson-vt.js"></script>
<script>
  const tileIndex = new GeoJSONVT(geoJSON);
</script>

Common Parameters

geojson-vt provides a set of adjustable parameters. The default values are sufficient for most scenarios:

  • maxZoom: the maximum zoom level for retaining detail, default 14, maximum 24
  • tolerance: simplification tolerance; the larger the value, the more obvious the simplification, default 3
  • extent: tile extent (width and height), default 4096
  • buffer: buffer around the tile, default 64, to avoid features being cut too fragmentarily at tile edges
  • indexMaxZoom: the maximum level of the initial index, default 5; above that, generated on demand
  • indexMaxPoints: the maximum number of points in a single tile in the index, default 100000
  • promoteId / generateId: settings related to feature id; the two cannot be used at the same time

If you want to pre-generate all tiles at once, set indexMaxZoom and maxZoom to the same value, set indexMaxPoints to 0, and then get tile coordinates from tileCoords.

Application in Mainstream Frameworks

The ecosystem of geojson-vt is quite complete. In MapLibre GL JS, its maintained version @maplibre/geojson-vt is used to support large GeoJSON data sources; OpenLayers official examples include geojson-vt integration, which can be used with VectorSource; in the Leaflet ecosystem, there are also vector tile plugins that depend on it (such as leaflet.vectorgrid). If you want to output the standard MVT binary format, you can work with vt-pbf to do server-side dynamic publishing in Node.js. In addition, the project also has a C++11 port, geojson-vt-cpp, for non-JS environments.

Summary

Previously, when doing front-end large GeoJSON rendering, if you used pre-slicing, the tiles had to be re-sliced whenever the data was updated; if you used a backend service, you had to maintain a set of interfaces and concurrency for a single data source. geojson-vt pushes the slicing step down entirely to the browser: the index is built once and tiles are produced on demand. From administrative divisions of a few dozen KB to point data at the million level, it can be rendered directly in mainstream WebGIS frameworks. For those doing data visualization and lightweight WebGIS, it is a practical choice with a very low learning cost.

PS: Note that it supports up to zoom level 24. For extremely large data, the first index construction will also take some time. It is recommended to put it in a Web Worker.

References

  1. geojson-vt GitHub repository: https://github.com/mapbox/geojson-vt/
  2. geojson-vt npm page: https://www.npmjs.com/package/geojson-vt
  3. MapLibre's geojson-vt documentation: http://maplibre.org/geojson-vt/
  4. OpenLayers geojson-vt integration example: https://openlayers.org/en/latest/examples/geojson-vt.html
  5. The Ultimate Guide to geojson-vt: Detailed Explanation of Browser-Side Dynamic GeoJSON Vector Tile Slicing Technology: https://blog.csdn.net/gitblog_00008/article/details/139108148