How to Set Up a Cesium ion Token in Gods Eye View: A Complete Configuration Guide

To set up a Cesium ion token in Gods Eye View, create a .env file in the project root with VITE_CESIUM_ION_TOKEN=your_token_here, which src/main.js reads at startup and assigns to Cesium.Ion.defaultAccessToken before initializing the 3D viewer.

Gods Eye View is a Vite-based 3D visualization application that renders globes using CesiumJS. The bilawalsidhu/gods-eye-view repository requires a valid Cesium ion access token to fetch terrain and imagery assets, configured through build-time environment variables consumed at runtime.

How the Token Flow Works in Gods Eye View

The application follows the standard Vite + CesiumJS integration pattern. The Cesium ion token must be available before any Cesium.Viewer instance is created, otherwise requests for Cesium-hosted assets return authentication errors.

In src/main.js, the application imports the Cesium library and immediately sets the global default access token:

import * as Cesium from "cesium";

// Set the default Cesium ion token from the build-time env var
Cesium.Ion.defaultAccessToken = import.meta.env.VITE_CESIUM_ION_TOKEN;

This assignment occurs before the application imports and executes src/mapStartup.js, which constructs the actual viewer instance. The repository's vite.config.js ensures that environment variables prefixed with VITE_ are forwarded to the client bundle.

Configuring Your Cesium ion Token

1. Obtain a Token from Cesium ion

Visit Cesium ion and sign in to generate an access token from your dashboard. Copy the token string for the next step.

2. Create the Environment File

In the project root, create a file named .env and add your token:

VITE_CESIUM_ION_TOKEN=12345678-90ab-cdef-1234-567890abcdef

Vite automatically exposes variables prefixed with VITE_ to import.meta.env during both development and production builds. Never commit this file to version control.

3. Verify the Startup Sequence

The critical code in src/main.js handles the token assignment and validation:

import * as Cesium from "cesium";

const ionToken = import.meta.env.VITE_CESIUM_ION_TOKEN;
if (!ionToken) {
  console.warn("[Gods Eye View] No Cesium ion token found – the default basemap may not load.");
}
Cesium.Ion.defaultAccessToken = ionToken;

// Viewer creation follows in mapStartup.js
import { createViewer } from "./mapStartup.js";
createViewer();

Because src/mapStartup.js is imported after the token assignment, the createViewer function can instantiate new Cesium.Viewer without additional token configuration.

Alternative Runtime Token Injection

If you cannot store the token in a .env file, the repository supports runtime injection via URL query parameters.

Add the following fallback logic to src/mapStartup.js or src/main.js:

// Optional: read token from URL if not provided via env
if (!Cesium.Ion.defaultAccessToken) {
  const urlToken = new URLSearchParams(window.location.search).get("cesiumIonToken");
  if (urlToken) {
    Cesium.Ion.defaultAccessToken = urlToken;
  }
}

Access the application with ?cesiumIonToken=your_token_here to override the environment variable.

Critical Files in the Token Pipeline

Understanding these three files ensures successful authentication:

• src/main.js: Reads import.meta.env.VITE_CESIUM_ION_TOKEN and assigns it to Cesium.Ion.defaultAccessToken before any viewer initialization occurs.
• src/mapStartup.js: Contains the createViewer function that instantiates the Cesium Viewer; relies entirely on the global token set during startup.
• vite.config.js: Configures the Vite build system to expose VITE_ prefixed environment variables to the client bundle.

Summary

• Gods Eye View requires a Cesium ion token to render 3D terrain and satellite imagery from Cesium ion servers.
• Store your token in a root-level .env file as VITE_CESIUM_ION_TOKEN.
• The token is automatically injected into the client bundle and assigned to Cesium.Ion.defaultAccessToken in src/main.js.
• This assignment must complete before src/mapStartup.js creates the Cesium Viewer instance.
• For temporary testing, you can pass the token via the cesiumIonToken URL query parameter.

Frequently Asked Questions

What happens if I don't set a Cesium ion token?

If VITE_CESIUM_ION_TOKEN is undefined, src/main.js logs a console warning and CesiumJS attempts to use a default token, which may be rate-limited or expired. The default basemap and terrain will fail to load, leaving you with a blank globe or 401 authentication errors in the browser's network tab.

Can I use different tokens for development and production?

Yes. Create .env.development and .env.production files in the project root. Vite loads .env.development during npm run dev and .env.production during npm run build, allowing you to use restricted development tokens and production-specific access keys without manual switching.

Where is the Cesium Viewer actually created?

According to the source code in bilawalsidhu/gods-eye-view, the Viewer instantiation occurs in src/mapStartup.js inside the createViewer function. This file is imported by src/main.js only after the token has been set, ensuring the global Cesium.Ion.defaultAccessToken is already configured.

Is it safe to commit the .env file to version control?

No. The .env file contains sensitive access credentials. Add .env to your .gitignore file immediately after creation. For production deployments, inject the VITE_CESIUM_ION_TOKEN through your hosting platform's environment variable interface rather than committing the file.

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