maplibre-tile-sources

What this skill does

# MapLibre Tile Sources

MapLibre GL JS does not ship with map data. You provide a **style** that references **sources** — URLs or inline data that MapLibre fetches and renders. MapLibre works equally well for a store locator with 200 addresses, a city transit map, and a global basemap — the right source type depends on geographic scale and level of detail, update frequency, infrastructure constraints, and use case.

## When to Use This Skill

- Setting up a new MapLibre map and choosing where your data comes from
- Deciding between GeoJSON, serverless tiles, hosted services, a combination thereof, or self-hosted options
- Configuring glyphs (fonts) and sprites so labels and icons render
- Debugging blank maps or missing tiles
- Migrating from Mapbox and need equivalent tile sources and style setup

## How styles and sources work

A **style** (a style JSON, style document, or style object) is the configuration you pass to MapLibre. It contains the specific rendering rules governed by the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/), maintained with parity for MapLibre GL JS and MapLibre Native.

You can use a **style URL** from a provider — that URL references a style with sources, layers, glyphs, and sprite. Or you can **build your own style** and configure each yourself.

A style has three main components:

- **Sources** — Point to the actual data. Each source has a `type` and either inline data or a URL. MapLibre requests tiles or data as the viewport changes. The same source can back many layers (e.g. roads, water, and labels all from one vector URL).
- **Layers** — An ordered list defining what to draw and how. Each layer references a source (and for vector tiles, a `source-layer` name) and specifies paint/layout properties.
- **Glyphs and sprite** — Required for text and icons: URLs to font SDF stacks and icon spritesheets. Without them, labels and symbols won't appear.

**Source types:**

| Type         | Description                                                                                              |
| ------------ | -------------------------------------------------------------------------------------------------------- |
| `vector`     | Vector tiles — binary-encoded geometry and attributes; the primary format for basemaps and data overlays |
| `raster`     | Raster tile imagery — satellite photos, WMS/WMTS layers                                                  |
| `raster-dem` | Elevation tiles — for terrain rendering and hillshading                                                  |
| `geojson`    | GeoJSON data — inline object or URL; no tile server needed                                               |
| `image`      | A single georeferenced image — scanned maps, annotated overlays                                          |
| `video`      | Georeferenced video                                                                                      |

`vector` and `raster` are the most common for basemaps and data overlays. `geojson` is ideal for small datasets or interactive data that doesn't need tiling. `raster-dem` is used for terrain and hillshade effects, as well as emerging use cases in scientific visualization. `image` and `video` sources are the least common, but let you georeference static images (such as a scanned map, chart, or overlay) or georeferenced videos as map layers.

## GeoJSON and Direct Data Sources

For many use cases you don't need a tile service. MapLibre can render points, lines, or polygons directly from an inline GeoJSON object or a URL to a GeoJSON file. The entire dataset is downloaded and parsed in the browser; MapLibre handles rendering client-side.

```javascript
map.addSource('my-data', {
  type: 'geojson',
  data: '/path/to/data.geojson' // or an inline GeoJSON object
});
map.addLayer({
  id: 'my-layer',
  type: 'fill',
  source: 'my-data',
  paint: { 'fill-color': '#0080ff', 'fill-opacity': 0.5 }
});
```

### GeoJSON performance thresholds

GeoJSON downloads the entire file on every load. This works well at small scale and degrades predictably:

| Range      | File size / feature count        | Behavior                                                                                                    |
| ---------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Sweet spot | < 2 MB / < 5,000 features        | Instantaneous loading, smooth interaction                                                                   |
| Lag zone   | 5–20 MB / up to ~50,000 features | 1–3s parse delay; mobile may struggle; optimize by simplifying geometries and reducing coordinate precision |
| Crash zone | > 50 MB / > 100,000 features     | High risk of browser freeze or crash; switch to vector tiles                                                |

GeoJSON is **lossless** (exact coordinates preserved) and gives you full client-side access to feature properties — ideal for interactive data, dynamic updates, and datasets where you need to query or modify features without a server round-trip.

If your dataset exceeds these thresholds, or if you need zoom-dependent rendering (less detail at lower zoom levels), consider vector tiles instead.

### Other formats and the cloud-native ecosystem

The choice of data source is shaped by more than performance: data type, update frequency, access patterns, and the broader geospatial ecosystem all factor in. Many formats (FlatGeobuf, GeoParquet, Cloud-Optimized GeoTIFF, KML, GPX, and more) can be displayed in MapLibre via plugins and custom protocols. The cloud-native geospatial ecosystem — formats designed for HTTP range requests and distributed storage — is evolving rapidly and increasingly relevant for web maps. A separate skill will cover this in depth; for now, see the [Map Rendering Plugins](https://github.com/maplibre/awesome-maplibre#map-rendering-plugins) and [Utility Libraries](https://github.com/maplibre/awesome-maplibre#utility-libraries) sections of awesome-maplibre.

## When You Need Tiles

Vector tiles load only the data visible in the current viewport, in a compact binary format. Use them when:

- Your dataset exceeds GeoJSON's practical limits
- You need zoom-dependent rendering (different levels of detail at different zoom levels)
- You need global or regional reference layers, such as land and water, roads, place names, etc. (i.e., basemap data)
- Bandwidth efficiency matters at scale

### Vector tiles vs. raster tiles

When you need tiles, you'll choose between two tile types:

**Vector tiles** encode geometry and feature attributes as compact binary data (Mapbox Vector Tile format, or the newer [MapLibre Tile / MLT](https://maplibre.org/maplibre-tile-spec/)). MapLibre renders and styles them client-side:

- Styles can be changed without regenerating tiles
- Features are queryable (click, hover interactions)
- Text renders crisply at any zoom or screen density
- Significantly smaller file sizes than equivalent raster tiles

**Raster tiles** are pre-rendered images (PNG, JPEG, or WebP) at each zoom level, displayed by MapLibre as-is:

- No client-side styling or feature querying
- Larger file sizes, but simpler to generate and serve
- Good fit for satellite/aerial imagery, WMS/WMTS integration, or rendered styles that don't need client-side customization

Most MapLibre workflows use vector tiles; increasing numbers are integrating `raster-dem` sources e.g. for terrain rendering. Use raster tiles when you need satellite/aerial imagery, when integrating with existing WMS or WMTS services, or when you need a pre-rendered cartographic style.

### Using MapLibre with Leaflet

[Leaflet](https://leafletjs.com/) is a widely used JavaScript mapping library that supports only raster tiles. If your app is built on Leaflet, [MapLibre GL Leaflet](https://github.com/maplibre/maplibre-gl-leaflet) lets you pre-render a MapLibre GL compatible st