@stackwright-pro/cesium

CesiumJS 3D globe map provider for Stackwright Pro

One-line swap from MapLibre 2D to Cesium 3D globe. All existing type: map and type: map_pulse YAML renders on a 3D globe -- zero content changes.

Quick Start

pnpm add @stackwright-pro/cesium cesium

// _app.tsx or layout.tsx
import { registerCesiumProvider } from '@stackwright-pro/cesium';

// With Cesium Ion (terrain + high-res imagery):
registerCesiumProvider({
  ionToken: process.env.NEXT_PUBLIC_CESIUM_ION_TOKEN,
});

// Or without (basic globe, OSM imagery):
registerCesiumProvider();

One-Line Swap from MapLibre

- import { registerMapLibreProvider } from '@stackwright/maplibre';
- registerMapLibreProvider();
+ import { registerCesiumProvider } from '@stackwright-pro/cesium';
+ registerCesiumProvider();

Cesium Asset Setup

CesiumJS requires static assets (web workers, etc.) served from a known path.

Option A: Copy to public/ (recommended)

cp -rf node_modules/cesium/Build/Cesium/ public/cesium/

Add to .gitignore:

public/cesium/

Option B: CDN (development only)

registerCesiumProvider({
  baseUrl: 'https://cesium.com/downloads/cesiumjs/releases/1.122/Build/Cesium/',
  ionToken: '...',
});

Features

| Feature | MapLibre (2D) | Cesium (3D) | | ----------------- | :-----------: | :--------------------: | | Markers | Y | Y | | Polylines | Y | Y (clamped to terrain) | | Polygons | Y | Y | | GeoJSON | Y | Y | | Globe view | -- | Y | | Terrain elevation | -- | Y | | 3D buildings | -- | Y (via Cesium Ion) | | Sun lighting | -- | Y | | Marker altitude | -- | Y | | SSR-safe | Y | Y |

YAML -- Zero Changes Required

# Works with BOTH MapLibre and Cesium -- the provider is an implementation detail
- type: map_pulse
  collection: vessels
  center: { lat: 29.76, lng: -95.36 }
  zoom: 10
  markerMapping:
    lat: latitude
    lng: longitude
    label: vesselName
    popup: '{{ vesselName }} -- {{ speed }}kn'
    colorField: status
    colorMap:
      underway: '#22c55e'
      moored: '#3b82f6'

Cesium-Specific MapConfig Options

# These fields activate when Cesium is the provider:
- type: map
  center: { lat: 40.71, lng: -74.00 }
  zoom: 12
  view: globe # 'globe' (3D) or 'map' (2D) -- Cesium supports both
  terrain: true # Enable terrain elevation

Environment Variables

| Variable | Purpose | | ------------------------------ | ------------------------------------------ | | NEXT_PUBLIC_CESIUM_ION_TOKEN | Cesium Ion token (client-safe for Next.js) | | CESIUM_ION_TOKEN | Alternative (server-side only) |

License

Proprietary -- Per Aspera LLC

CesiumJS itself is Apache-2.0 licensed. Cesium Ion services require a separate Cesium Ion account.