Language

Source types.

Every source kind the runtime can attach to. Each section below documents the type's intended use, accepted fields, and caveats — pick the one that matches the upstream you have.

`geojson`

Default

GeoJSON from a URL, an embedded literal, or pushed at runtime. Tiled on-demand.

Pulls (or reads) the entire FeatureCollection, then tiles it client-side in a worker (geojson-vt port) before routing per-tile MVT through the same compile pipeline PMTiles archives use. Best for moderate datasets (≤ ~50 MB) — countries, ports, points of interest. For larger worlds reach for PMTiles.

Fields

url

optional. HTTP(S) URL of the .geojson file. Relative paths resolve against the playground / host page baseURL. Mutually exclusive with `data`.

data

optional. An embedded GeoJSON FeatureCollection object literal — no fetch, no separate file. The features are tiled immediately at compile time. Mutually exclusive with `url`.

Example

source world {
  type: geojson
  url: "data/countries.geojson"
}

// Or embed the FeatureCollection directly:
source pins {
  type: geojson
  data: {
    "type": "FeatureCollection",
    "features": [
      { "type": "Feature",
        "geometry": { "type": "Point", "coordinates": [127.0, 37.5] },
        "properties": { "name": "Seoul" } }
    ]
  }
}

Notes

• CORS-sensitive — the host must send `Access-Control-Allow-Origin` (the `url` form only).
• Tile generation runs on a Web Worker; main thread stays smooth.
• The embedded `data: { … }` form tiles the literal at compile time — no network round-trip, ideal for small fixed overlays.
• Declaring neither `url` nor `data` yields an empty source the host populates at runtime via `map.setSourceData(sourceId, featureCollection)`.

`pmtiles`

Recommended for vector basemaps

PMTiles archive — MVT inside a single byte-range-served file.

Lazy-loaded: only the header + visible-frustum tiles are fetched. Scales to planet-size archives (multi-GB) without memory blow-up. Backed by `attachPMTilesSource` — same code path serves both `.pmtiles` archives and TileJSON manifests (see below).

Fields

url

URL of the `.pmtiles` archive. Server must support HTTP byte-range requests (`Accept-Ranges: bytes`).

layers

optional. Optional MVT source-layer subset — `["water", "roads"]`. The decoder skips other layers, reducing per-tile work. Defaults to whatever layers the registered xgis `sourceLayer:` filters reference.

Example

source world {
  type: pmtiles
  url: "/tiles/protomaps-v4.pmtiles"
  layers: ["water", "landuse", "transportation"]
}

Notes

• Per-source-layer slicing is automatic — multiple xgis layers on the same source share decoded tile data.
• Sub-tile generation handles over-zoom past the archive's `maxZoom` by clipping parent geometry.
• CORS rules for the archive's host apply; range-request preflight matters in browsers.

`tilejson`

Manifest pointing at XYZ MVT

TileJSON manifest. Runtime fetches the manifest, then per-tile `.pbf` from the listed template.

Use when the upstream is a vector tile server (e.g. `tiles.openfreemap.org/planet`) rather than a single archive. The runtime parses the TileJSON to discover the tile URL template, vector_layers metadata, and zoom range, then drives the same backend as `pmtiles`.

Fields

url

URL returning a TileJSON 3.0 document (JSON). The `tiles[]` array supplies the per-tile URL template.

layers

optional. Same semantics as the `pmtiles` source.

Example

source openmaptiles {
  type: tilejson
  url: "https://tiles.openfreemap.org/planet"
}

Notes

• The Mapbox style converter at /convert auto-emits `type: tilejson` when the upstream URL has no `.pmtiles` extension.
• No `version` / no `tiles[]` in the response triggers a soft-fail — the catalog stays empty so the rest of the demo still loads.

`raster`

XYZ tile server

Raster tile server using `{z}/{x}/{y}` template URLs.

For OSM-style PNG/JPG tile services. The runtime activates the raster renderer only when at least one xgis layer references the source.

Fields

url

`{z}/{x}/{y}` template, e.g. `"https://tile.openstreetmap.org/{z}/{x}/{y}.png"`.

Example

source osm {
  type: raster
  url: "https://tile.openstreetmap.org/{z}/{x}/{y}.png"
}

Notes

• Most public OSM tile servers ban automated traffic — use your own server or a paid provider for production.
• Raster + vector can mix in one map: stack a vector overlay on top of a raster basemap by listing the raster source first.

Specifications