Adding Layers¶

Your data layers live in app/layers.ts, which exports a layers array that settings.ts imports as settings.layers. (It's a separate file purely to keep settings.ts readable — everything downstream treats it as one array.)

Each entry is a typed object with a type discriminator that selects the loader:

import type { LayerConfig } from '@/core/types'

export const layers: LayerConfig[] = [
  {
    id: 'parks',
    type: 'geojson',
    name: 'National Parks',
    geometryType: 'polygon',
    url: './layers/parks.geojson',
    symbology: { kind: 'simple', color: '#2c8a3e' },
  },
  // …
]

Order matters: it sets the layer-list display order, and groups are positioned by the first appearance of their group name.

Common fields (every layer type)¶

Where files live¶

• Local files go in app/layers/. Reference them as './layers/<file>'. Vite resolves the path at build time. Supported extensions: .geojson, .pmtiles, .fgb, .parquet / .geoparquet.
• Remote URLs (http:// / https://) are used as-is. Remote sources must be CORS-enabled.

geojson¶

The simplest type. One source, automatically split into fill / line / circle sublayers filtered by geometry — so a single file can mix points, lines, and polygons.

{
  id: 'airports',
  type: 'geojson',
  name: 'US Major Airports',
  geometryType: 'point',
  url: 'https://example.com/airports.geojson',
  symbology: { kind: 'ref', name: 'airports-by-passengers' },
}

pmtiles¶

PMTiles vector tiles — a single cloud-native archive that streams only the tiles in view. Ideal for large datasets.

{
  id: 'counties',
  type: 'pmtiles',
  name: 'US Counties',
  geometryType: 'polygon',
  url: './layers/US_counties.pmtiles',
  sourceLayer: 'US_counties',
  symbology: { kind: 'simple', color: '#838291', strokeColor: '#fff', strokeWidth: 1 },
}

flatgeobuf¶

FlatGeobuf (.fgb) — a streaming vector format. Decoded into a GeoJSON source, so it flows through the same sublayer / popup / legend pipeline.

• 'all' reads the whole file once into memory — fine for small/medium files (same ceiling as GeoJSON).
• 'dynamic' fetches only the features in the current viewport via the file's spatial index (HTTP Range requests), refetched on map move — the way to use a large remote .fgb (hundreds of MB / GB) without downloading it whole.

esri¶

ArcGIS REST services via esri-gl. A service discriminator picks the family. esri-gl creates the source; the kit adds the styled layer(s).

Feature service¶

{
  id: 'buoys',
  type: 'esri',
  service: 'feature',
  name: 'NDBC Buoys',
  geometryType: 'point',
  url: 'https://services5.arcgis.com/.../FeatureServer/0',
  minZoom: 4,
  symbology: { kind: 'simple', color: '#a5d7f7', radius: 5, strokeColor: '#fff', strokeWidth: 1 },
  popup: { displayType: 'rich' },
}

For feature services, symbology is optional: provide it for kit styling, or omit it to use the service's own ArcGIS renderer. Extra fields: where (an ArcGIS where clause, default '1=1').

Raster services¶

{
  id: 'usa-dynamic', type: 'esri', service: 'dynamic',
  name: 'USA States/Counties',
  url: 'https://sampleserver6.arcgisonline.com/.../USA/MapServer',
  layers: [2, 3],   // dynamic only: which MapServer sublayers to draw
  opacity: 0.7,
}

dynamic takes an optional layers (sublayer ids). tiled takes only the common fields. Both are visibility + opacity only.

geoparquet¶

GeoParquet — parsed in a Web Worker via parquet-wasm + apache-arrow. The worker decodes the WKB geometry to GeoJSON and feeds a GeoJSON source.

Labels¶

Any vector layer can carry text labels via a label block. Rendered as a companion MapLibre symbol sublayer.

Set app-wide label defaults once via ui.layerDefaults.label.

Hiding a layer from the legend¶

Set hideFromLegend: true on any layer to keep it on the map and in the layer list but omit it from the legend. (This works for every symbology kind, unlike the raw-symbology legend: { kind: 'hidden' } which is raw-only — see Symbology.)