MapLibre Agent Skills

---
name: maplibre-tile-sources
description: Choosing what form your data needs for MapLibre GL JS — GeoJSON read straight from a file versus vector or raster tiles, the feature-count and file-size thresholds where each stops working, and how a basemap and your own data combine as separate sources. Use when deciding which source type a dataset needs, not when hosting or configuring one.
metadata:
  status: verified
---

# 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.

This skill is about **choosing** that source type. For getting a configured source to render see [maplibre-source-wiring](../maplibre-source-wiring/SKILL.md).

## When to Use This Skill

- Setting up a new MapLibre map and choosing where your data comes from
- Deciding between GeoJSON and tiles for a dataset of a given size
- Working out whether you need tile infrastructure at all
- Planning how a basemap and your own data fit together

## 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** — URLs to font SDF stacks and icon spritesheets. `sprite` has no fallback: a missing icon is omitted and the console warns `Image "<id>" could not be loaded`; use `map.hasImage(id)` to test whether an icon ID is defined. `glyphs` does have one on GL JS ≥ 5.11.0 (text still renders, in a local/system font) — see [maplibre-fonts-glyphs](../maplibre-fonts-glyphs/SKILL.md) for the mechanism and its limits. Production styles should still supply both explicitly.

**Source types:**