Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Search & research

maplibre-source-wiring

Getting a MapLibre GL JS source to actually render — TileJSON `url` versus hand-wired `tiles` templates, matching `source-layer` names to the tile schema, layer order and inserting below labels, `promoteId` and the feature ids that feature state needs, and the CORS and glyph failures behind a blank map. Use when a source is configured but nothing is drawing, or when setFeatureState does nothing.

maplibre · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add maplibre/maplibre-agent-skills --skill maplibre-source-wiring

About this skill


name: maplibre-source-wiring description: Getting a MapLibre GL JS source to actually render — TileJSON url versus hand-wired tiles templates, matching source-layer names to the tile schema, layer order and inserting below labels, promoteId and the feature ids that feature state needs, and the CORS and glyph failures behind a blank map. Use when a source is configured but nothing is drawing, or when setFeatureState does nothing. status: verified

MapLibre Source Wiring

You have a tile URL or a data file and a style, and the map is blank, drawing at the wrong scale, or drawing in the wrong order. This skill covers connecting a source to a style correctly, and the failure modes that look identical from the outside.

When to Use This Skill

The source is already configured and the map is wrong in a way that produces no error. These are symptoms as you would observe them, before you know the cause:

  • The map is blank, or a layer you added draws nothing, and the console is clean
  • A custom style renders nothing against a tile source that works with the provider's own style
  • The basemap is blurry, or sits at a different scale than everything drawn on top of it
  • Data you added has covered the street names
  • Icons are missing while the rest of the map draws fine
  • Hover or click highlighting does nothing at all, and no error is raised
  • You have a tile endpoint and are unsure which source type it needs, or whether to point url at its TileJSON instead of hand-writing tiles

Not this skill. Text in the wrong font, missing scripts, or self-hosting glyph PBFs — maplibre-fonts-glyphs. Deciding the colors, type, and drawing order of a style you are designing — maplibre-cartography. Deciding whether a dataset belongs in GeoJSON or vector tiles at all — maplibre-tile-sources.

Referencing tiles: url vs tiles

Tiles are addressed by zoom (Z), column (X), and row (Y) — a universal scheme across raster and vector tile sources (see the OpenStreetMap wiki for more information). In a MapLibre source, you reference tiles either directly via a tiles URL template or via a url pointing to a TileJSON endpoint.

When a TileJSON endpoint is available, prefer url. MapLibre fetches the document and reads the tile URL template, zoom range, bounds, attribution, and (for vector tiles) the available source-layers automatically. Tile servers like Martin and tileserver-gl generate TileJSON endpoints for every tileset they serve, as do many hosted providers.

When no TileJSON endpoint exists — for example, a raw raster tile service that gives you a URL template directly — use the tiles array and specify any metadata (minzoom, maxzoom, attribution) in the source definition yourself.

url to a TileJSON endpoint:

{
  "type": "vector",
  "url": "https://example.com/tiles.json"
}

tiles array:

{
  "type": "vector",
  "tiles": ["https://example.com/tiles/{z}/{x}/{y}.pbf"],
  "minzoom": 0,
  "maxzoom": 14
}

The cost of hand-wiring tiles is that MapLibre has no zoom range unless you supply one, and will assume maxzoom: 22 — requesting zoom levels the tileset doesn't contain, which come back empty. This is why url is the default advice wherever a TileJSON endpoint exists. (For PMTiles specifically the same rule applies and the consequence is sharper — see maplibre-pmtiles-patterns.)

Nothing renders: source-layer and the tile schema

The most common cause of a custom style rendering nothing against a working tile source is a source-layer mismatch.

A vector tile source contains named layers — transportation, water, landuse and so on — and every style layer that draws from it must name one exactly:

{
  "id": "roads",
  "type": "line",
  "source": "basemap",
  "source-layer": "transportation"
}

source-layer is required for vector sources and must match the tile schema exactly. A typo or a name from a different schema produces no error and no output — the layer simply draws nothing.

Find the real names in the TileJSON. For vector sources, the TileJSON vector_layers field lists each available source-layer, its attribute fields, and its zoom range. This is the authoritative reference when it is present — but vector_layers is optional in TileJSON 3.0, and providers are inconsistent about supplying it. Its absence does not mean there is no schema: identify the schema by name (below) and work from its published layer list. If you use a provider's pre-built style URL, the schema is already matched for you; the mismatch only appears when you write your own layers.

Pre-defined tile schemas

When building a custom style you need to know the tile schema — the source-layer names and their properties. Common schemas:

  • OpenMapTiles — the most widely adopted schema, based on OpenStreetMap data. Rich and detailed, with source-layers like transportation, water, landuse, poi. The largest ecosystem of community styles targets this schema.
  • Shortbread — an open standard designed to be minimal and interoperable, not tied to any single vendor. Simpler structure than OpenMapTiles; a clean foundation if you're building styles from scratch.
  • Protomaps — purpose-built for the Protomaps PMTiles basemap ecosystem. Flat, simple structure with source-layers like land, water, roads, places; optimized for serverless delivery. Published layer list: docs.protomaps.com/basemaps/layers.

Each of these publishes its layer list as documentation (see References). None carries a machine-readable version marker, so checking a schema means re-reading the page; nothing can poll it for changes.

When generating tiles with Planetiler or tippecanoe

Read the complete source ↗