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

> Configure environment variables for Cesium Ion token provisioning in GeoLibre. Learn how to set VITE_CESIUM_TOKEN or CESIUM_TOKEN for seamless integration.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: how-to-guide
- Published: 2026-08-02

---

**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)](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:

```text
VITE_CESIUM_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

```

Export in your terminal before building:

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

```

Import and validate the token in your code:

```typescript
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)](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:

```typescript
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:

```typescript
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)](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)](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)](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.