How to Configure Environment Variables for Cesium Ion Token Provisioning in GeoLibre

GeoLibre provisions Cesium Ion tokens via the getCesiumIonToken() helper, which checks VITE_CESIUM_TOKEN first, then falls back to CESIUM_TOKEN, allowing configuration at build time through .env files or at runtime through the Desktop Settings UI and window.__GEOLIBRE_RUNTIME_ENV__.

GeoLibre is an open-source geospatial visualization platform that requires a Cesium Ion access token to enable 3D globe functionality. Configuring environment variables for Cesium Ion token provisioning involves understanding the resolution hierarchy implemented in the core runtime environment module according to the opengeos/GeoLibre source code.

How Cesium Ion Token Resolution Works

The token resolution logic is centralized in the core package. In [packages/core/src/runtime-env.ts](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/runtime-env.ts), the getCesiumIonToken() function implements a prioritized lookup mechanism:

1. VITE_CESIUM_TOKEN – The primary variable, automatically exposed by Vite when prefixed with VITE_.
2. CESIUM_TOKEN – A fallback for non-Vite environments or legacy builds.

Both values are trimmed of whitespace. If the resulting string is empty, the function returns undefined, which disables the 3D globe toggle in the UI.

Build-Time Environment Variables

When building GeoLibre from source, Vite injects environment variables at compile time. Any variable intended for client-side code must use the VITE_ prefix. The build process embeds these values into the bundle, making them available via import.meta.env.

Runtime Environment Overrides

For the Desktop application, users can modify tokens without rebuilding. The runtime environment uses window.__GEOLIBRE_RUNTIME_ENV__ as an override layer. When a user saves a token in the Settings UI, the application stores it in localStorage via the desktop settings hook and projects it onto the runtime object, emitting a geolibre:runtime-env-change event to notify components.

Method 1: Build-Time Configuration

Set the token before compiling the application. Create a .env file in the project root or export the variable in your shell.

Create a .env file:

VITE_CESIUM_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Export in your terminal before building:

export VITE_CESIUM_TOKEN="your-cesium-ion-token"
npm run build

Import and validate the token in your code:

import { getCesiumIonToken } from "@geolibre/core";

const token = getCesiumIonToken();
if (token) {
  console.log("Cesium Ion token configured:", token);
} else {
  console.warn("No Cesium Ion token found; 3D globe will be disabled");
}

Method 2: Runtime Configuration

For dynamic configuration without rebuilding, use the runtime environment object. This method is used by the Desktop Settings interface defined in [apps/geolibre-desktop/src/hooks/useDesktopSettings.ts](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/hooks/useDesktopSettings.ts).

Set the token manually in the browser console or through a custom script:

window.__GEOLIBRE_RUNTIME_ENV__ = {
  VITE_CESIUM_TOKEN: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
};

// Notify GeoLibre components that the environment has changed
window.dispatchEvent(new Event("geolibre:runtime-env-change"));

Listen for changes in React components to update the globe state dynamically:

import { getCesiumIonToken } from "@geolibre/core";
import { useEffect, useState } from "react";

function MapComponent() {
  const [cesiumToken, setCesiumToken] = useState(getCesiumIonToken());

  useEffect(() => {
    const handleEnvChange = () => {
      setCesiumToken(getCesiumIonToken());
    };
    
    window.addEventListener("geolibre:runtime-env-change", handleEnvChange);
    return () => window.removeEventListener("geolibre:runtime-env-change", handleEnvChange);
  }, []);

  return cesiumToken ? <CesiumViewer token={cesiumToken} /> : <div>3D Globe disabled</div>;
}

Validating the Token in Components

The [apps/geolibre-desktop/src/components/layout/MapGrid.tsx](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/components/layout/MapGrid.tsx) file demonstrates the standard validation pattern. The component initializes state by calling getCesiumIonToken() and subscribes to runtime environment changes to toggle the Cesium integration layers.

If the token is present, the application enables "World Imagery" and "Terrain" layers through the CesiumLayerSync and CesiumCanvas modules as described in [docs/architecture.md](https://github.com/opengeos/GeoLibre/blob/main/docs/architecture.md). If the token is undefined, these modules remain inactive.

Summary

• Use VITE_CESIUM_TOKEN for build-time configuration in Vite-based builds, or CESIUM_TOKEN as a fallback.
• Call getCesiumIonToken() from @geolibre/core to retrieve the resolved token with whitespace trimmed.
• Set window.__GEOLIBRE_RUNTIME_ENV__.VITE_CESIUM_TOKEN and dispatch geolibre:runtime-env-change for runtime configuration without rebuilding.
• Check for undefined return values to conditionally disable 3D globe features when no token is provisioned.

Frequently Asked Questions

What is the difference between VITE_CESIUM_TOKEN and CESIUM_TOKEN?

VITE_CESIUM_TOKEN is the preferred variable for Vite-based builds because Vite automatically exposes only environment variables prefixed with VITE_ to the client-side code. CESIUM_TOKEN serves as a fallback for non-Vite environments or when the build system does not require the prefix, as noted in the optional 3D globe credentials section of [docs/getting-started.md](https://github.com/opengeos/GeoLibre/blob/main/docs/getting-started.md).

Can I change the Cesium Ion token without rebuilding the application?

Yes. The GeoLibre Desktop application supports runtime configuration through the Settings UI, which persists the token in localStorage and projects it onto window.__GEOLIBRE_RUNTIME_ENV__.VITE_CESIUM_TOKEN. Dispatching the geolibre:runtime-env-change event forces components to re-read the token immediately without requiring a rebuild.

Where does GeoLibre store the runtime token configuration?

Runtime tokens are stored in the browser's localStorage via the useDesktopSettings hook and simultaneously mirrored to window.__GEOLIBRE_RUNTIME_ENV__. This dual storage ensures persistence across sessions while providing synchronous access for the getCesiumIonToken() resolver.

Why is my 3D globe not appearing even after setting the token?

The globe remains disabled if getCesiumIonToken() returns undefined or an empty string. Verify that your variable contains non-whitespace characters and that you have dispatched the geolibre:runtime-env-change event after runtime modifications. Additionally, check that the MapGrid component or your custom implementation is actually listening for these environment change events.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}