Map & Camera¶

The map block in app/settings.ts sets the map's initial view, camera limits, and the optional globe projection.

map: {
  style: 'https://tiles.openfreemap.org/styles/positron',
  center: [-98.5, 39.5],
  zoom: 4,
},

Fields¶

Field	Type	Default	Description
`style`	`string \\| StyleSpecification`	— (required)	The initial basemap. A URL to a MapLibre style JSON, or an inline style object
`center`	`[lng, lat]`	— (required)	Initial map center
`zoom`	`number`	— (required)	Initial zoom level
`pitch`	`number`	`0`	Initial camera tilt in degrees (0 = straight down). Common for 3D / oblique views
`bearing`	`number`	`0`	Initial rotation in degrees
`backgroundColor`	`string`	`'#000000'`	Fill behind the map — shows beyond the globe's edge, past a flat map's edges, and before tiles load
`minZoom`	`number`	`1.5`	Camera zoom floor — the user can't zoom out past this
`maxZoom`	`number`	`16`	Camera zoom ceiling
`maxBounds`	`LngLatBoundsLike`	none	Clamp panning to a region, most simply `[[west, south], [east, north]]`
`globe`	`GlobeConfig`	none	Globe projection + starry backdrop + auto-spin (see below)

Camera clamp vs. layer zoom range

map.minZoom / map.maxZoom bound the camera — how far the user can zoom the whole map. These are different from a layer's minZoom / maxZoom, which control at what zooms an individual layer renders (see Adding Layers).

World-wide maxBounds

Don't use exactly -180 / 180 for longitude — MapLibre crashes on load. Inset slightly instead, e.g. [[-179.9999, -85], [179.9999, 85]].

Example with camera limits¶

map: {
  style: 'https://tiles.openfreemap.org/styles/liberty',
  center: [-122.4, 37.8],
  zoom: 11,
  pitch: 45,
  minZoom: 9,
  maxZoom: 18,
  maxBounds: [[-123.2, 37.2], [-121.6, 38.3]],  // San Francisco Bay Area
},

Basemaps¶

map.style is the initial basemap. The full list the user can switch between lives in the separate basemaps array, consumed by the Basemap widget:

basemaps: [
  { id: 'positron', name: 'Positron', style: 'https://tiles.openfreemap.org/styles/positron' },
  { id: 'liberty',  name: 'Liberty',  style: 'https://tiles.openfreemap.org/styles/liberty' },
  // … an inline style object also works (e.g. a raster OSM basemap)
],

Field	Type	Description
`id`	`string`	Unique id. Convention: `<name>-<source>` kebab-case (e.g. `positron-openfreemap`) — also the thumbnail filename (see Basemap widget)
`name`	`string`	Display name in the switcher. Convention: `Name (Source)`
`style`	`string \\| StyleSpecification`	Style URL or inline style object
`thumbnail`	`string`	Optional explicit thumbnail image
`license`	`'commercial-safe' \\| 'restricted'`	Omit for commercial-safe (the default). See Commercial Use

Default catalog¶

The demo ships 17 basemaps: Esri World Imagery, five OpenFreeMap styles, and eleven VersaTiles themes. None require an API key.

Name	Source	Commercial use
Satellite (ESRI)	Esri World Imagery	Restricted — see Commercial Use
Positron (OpenFreeMap)	OpenFreeMap	✅
Liberty (OpenFreeMap)	OpenFreeMap	✅
Bright (OpenFreeMap)	OpenFreeMap	✅
Dark (OpenFreeMap)	OpenFreeMap	✅
Fiord (OpenFreeMap)	OpenFreeMap	✅
Satellite (VersaTiles)	VersaTiles	✅
Colorful (VersaTiles)	VersaTiles	✅
Colorful Dark (VersaTiles)	VersaTiles	✅
Natural (VersaTiles)	VersaTiles	✅
Natural Dark (VersaTiles)	VersaTiles	✅
Muted (VersaTiles)	VersaTiles	✅
Muted Dark (VersaTiles)	VersaTiles	✅
Gray (VersaTiles)	VersaTiles	✅
Gray Dark (VersaTiles)	VersaTiles	✅
Toner (VersaTiles)	VersaTiles	✅
Toner Dark (VersaTiles)	VersaTiles	✅

Globe projection¶

Add a globe block to start the map as a 3D globe with a starry backdrop, comets, an atmospheric halo, and an auto-spin. Omit it for a flat (mercator) map.

map: {
  /* … */
  globe: {
    enabled: true,               // start on the globe instead of mercator
    stars: true,                 // parallaxing starfield (globe-only)
    comets: true,                // shooting stars — requires stars
    atmosphere: true,            // glow around the globe's limb (default: on)
    spin: {
      direction: 'east',  // 'east' (default) | 'west'
      speed: 6,           // degrees/sec (default 6 ≈ 1 revolution/min)
      continuous: false,  // see below
    },
  },
},

Field	Type	Default	Description
`enabled`	`boolean`	`false`	Start on the globe projection. The native Globe control can still toggle it at runtime regardless
`stars`	`boolean`	`false`	A parallaxing starfield over `map.backgroundColor`
`comets`	`boolean`	`false`	Occasional shooting-star comets over the starfield. No effect unless `stars` is also `true`
`atmosphere`	`boolean`	`true`	A soft glow around the globe's limb
`starsZoomCutoff`	`number`	`7.3`	Zoom above which stars and comets hide
`spin`	`GlobeSpinConfig`	none	Auto-spin on load. Omit to disable
`spin.direction`	`'east' \\| 'west'`	`'east'`	`'east'` matches Earth's real rotation
`spin.speed`	`number`	`6`	Rotation rate in degrees of longitude per second
`spin.continuous`	`boolean`	`false`	When `false`, the spin stops permanently on the first user interaction ("attract mode"). When `true`, it pauses during interaction and resumes a moment after — a kiosk-style perpetual globe

atmosphere defaults to on

Unlike every other field here, atmosphere defaults to true — a bare globe: { enabled: true } already shows the halo. Set it to false explicitly to turn it off.

Zoom cutoff

Stars and comets hide above starsZoomCutoff. The atmosphere halo hides earlier, around zoom 3.3 (not configurable).

Stars, comets, and the atmosphere halo are adapted from Leonel J. Dias's technique for a globe atmosphere, halo, and comets.