Migrating from Mapbox.

Mental model differences

Mapbox GL JS is an imperative library — you instantiate a Map, call addLayer(), wire styling through paint property setters, ship glue code in JS. xgis is a language: the source is the program, and the compiler emits the WGSL.

Using the converter

Open /convert, click a preset chip (Liberty / Bright / Positron — three OpenFreeMap styles) or paste a URL pointing at any style.json. The page emits an .xgis source and a count badge showing how many features got dropped or rewritten.

Or skip the build step entirely — the splice-form import "url" directive fetches and runs the converter at runtime, so a one-liner inside your xgis source drops a full base map onto the canvas. Auto-detect only fires when the URL returns JSON shaped like a Mapbox v8 style (version + layers); plain xgis modules go through unchanged.

import "https://tiles.openfreemap.org/styles/bright"

source places { type: geojson, url: "places.geojson" }
layer my_pois {
  source: places
  | fill-rose-500 fill-opacity-80
}

The converter is also exported from the compiler package — call it from your build pipeline if you want to bake the converted xgis into your bundle (skips the runtime fetch).

import { convertMapboxStyle } from '@xgis/compiler'

const style = await fetch('https://tiles.openfreemap.org/styles/bright')
  .then(r => r.json())
const xgis = convertMapboxStyle(style)
// xgis is a string — feed to <XGISMap>.run() directly.

Compatibility matrix

Expression mapping

Common Mapbox expressions and their xgis equivalents. The converter applies these automatically — this is for when you're reading converter output and want to know what changed.

"line-width": [
  "interpolate", ["linear"],
  ["zoom"],
  11, 1,
  19, 2.5
]

| stroke-[interpolate(zoom, 11, 1, 19, 2.5)]

"fill-color": [
  "match",
  ["get", "class"],
  "park",  "#cfe7c1",
  "water", "#a4c8d5",
  "#dadada"
]

| fill match(.class) {
    "park"  -> #cfe7c1
    "water" -> #a4c8d5
    _       -> #dadada
  }

"fill-extrusion-height": [
  "coalesce",
  ["get", "render_height"],
  ["get", "height"],
  5
]

| fill-extrusion-height-[.render_height ?? .height ?? 5]

"filter": [
  "all",
  ["==", "$type", "LineString"],
  ["==", "class", "highway"]
]

filter: .class == "highway"
// $type dropped — geometry type
// is implied by the utility used

Caveats & gotchas