How to Configure Cesium Ion Token and Google Maps API Key in God’s Eye View

To configure the Cesium Ion token and Google Maps API key in the God’s Eye View project, create a .env file in the repository root with CESIUM_ION_TOKEN and GOOGLE_MAPS_API_KEY, then restart the Vite dev server so the build pipeline can inject them into the client bundle.

The bilawalsidhu/gods-eye-view application depends on these two external services to render 3-D basemaps and Street View imagery. Understanding the Cesium Ion token and Google Maps API key configuration is essential because the app validates both credentials at startup and will throw errors or display warnings if they are missing. The project uses Vite’s loadEnv mechanism to expose the secrets to browser modules through import.meta.env before the bundle executes.

Step-by-Step Configuration Guide

Obtain the Credentials

Before editing any project files, generate active API credentials for both platforms:

• Cesium Ion token – Sign in to Cesium Ion, navigate to Access Tokens, and generate a default access token with the scopes required for 3-D tile streaming.
• Google Maps API key – Open the Google Cloud Console, enable the Maps JavaScript API and the Street View Static API, then create a restricted API key tied to your domain.

Create the .env File

In the repository root, create a .env file that Git ignores by default. Add the two variables exactly as the application expects:

CESIUM_ION_TOKEN=YOUR_CESIUM_ION_TOKEN
GOOGLE_MAPS_API_KEY=YOUR_GOOGLE_MAPS_API_KEY

Do not commit this file. If you run separate development and production builds, you can also use .env.development or .env.production; Vite merges them automatically according to the current mode.

Restart the Development Server

Vite reads environment files before bundling, so you must restart the server for changes to take effect:

npm run dev

For production builds, run:

npm run build

During the build, vite.config.js loads the .env file via loadEnv and injects the values into the client bundle.

Verify the Integration

Open the application in a browser and confirm the following:

• The Cesium globe loads without a missing-token banner.
• Interactions that trigger Street View fallbacks return images successfully.

If either credential is invalid, the app surfaces the failure immediately at runtime.

How the Application Reads the Tokens

Vite Build Pipeline (vite.config.js)

The build pipeline in vite.config.js resolves the environment variables and hard-codes them into the client bundle through the define option:

// vite.config.js (excerpt)
'import.meta.env.CESIUM_ION_TOKEN': JSON.stringify(env.CESIUM_ION_TOKEN),
'import.meta.env.GOOGLE_MAPS_API_KEY': JSON.stringify(env.GOOGLE_MAPS_API_KEY),

This step makes import.meta.env.CESIUM_ION_TOKEN and import.meta.env.GOOGLE_MAPS_API_KEY available inside every browser-side module.

Runtime Validation (src/main.js)

At startup, src/main.js reads the injected variables and enforces that the Google key exists:

// src/main.js (excerpt)
const googleApiKey = import.meta.env.GOOGLE_MAPS_API_KEY;
if (!googleApiKey) {
  throw new Error('GOOGLE_MAPS_API_KEY not found. Set it as an environment variable.');
}
window.__GOOGLE_MAPS_API_KEY__ = googleApiKey;

If GOOGLE_MAPS_API_KEY is missing, the app halts with an explicit Error before any rendering occurs.

UI Feedback for Missing Tokens (src/ui.js)

When CESIUM_ION_TOKEN is absent, src/ui.js displays a placeholder message prompting the user to supply the token. This behavior prevents the Cesium viewer from failing silently and guides the developer toward the correct fix.

Street View Integration (src/locations.js)

Several UI components rely on the Google Maps key for geometry lookups and Street View images. The src/locations.js module retrieves the key from import.meta.env.GOOGLE_MAPS_API_KEY or the global fallback:

// src/locations.js (excerpt)
const apiKey = window.__GOOGLE_MAPS_API_KEY__ || import.meta.env.GOOGLE_MAPS_API_KEY;

async function fetchStreetView(lat, lng) {
  const url = `https://maps.googleapis.com/maps/api/streetview?size=640x640&location=${lat},${lng}&key=${apiKey}`;
  const response = await fetch(url);
  return response.blob(); // image data
}

Because src/main.js already validated and published the key to window.__GOOGLE_MAPS_API_KEY__, downstream modules can depend on it being present.

Summary

• The God’s Eye View project requires both a Cesium Ion token (CESIUM_ION_TOKEN) and a Google Maps API key (GOOGLE_MAPS_API_KEY) to function fully.
• Store both values in a .env file at the repository root; Vite loads them via loadEnv in vite.config.js and injects them into the bundle.
• src/main.js validates the Google key at startup and throws an error if it is missing, while src/ui.js warns when the Cesium token is absent.
• Restart the dev server after editing .env so the new values are picked up by the build pipeline.
• For CI/CD, pass the variables as environment variables in the build environment rather than committing a .env file.

Frequently Asked Questions

What happens if the Google Maps API key is missing?

src/main.js checks import.meta.env.GOOGLE_MAPS_API_KEY immediately at startup. If the value is falsy, the code throws new Error('GOOGLE_MAPS_API_KEY not found. Set it as an environment variable.'), which stops execution before the UI mounts.

Can I use .env.development or .env.production instead of .env?

Yes. Vite automatically merges mode-specific files such as .env.development and .env.production. You can keep local defaults in .env and override them per environment without changing tracked source files.

Is the .env file safe to commit to Git?

No. The .env file is ignored by default because it contains sensitive secrets. Exposing a Cesium Ion token or Google Maps API key in version control can lead to quota theft and unexpected charges. For automated builds, inject the values through your CI/CD provider’s secret management instead.

How do I supply these keys in a CI/CD pipeline?

Configure the CESIUM_ION_TOKEN and GOOGLE_MAPS_API_KEY variables directly in your build environment—for example, through GitHub Actions env: blocks or your hosting platform’s dashboard. Vite’s loadEnv will pick them up during npm run build even when no .env file exists on disk.

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