vite-plugin-cesium-engine

1.6.0 verified Mon Apr 27 auth: no javascript

Zero-config Vite plugin for @cesium/engine (v1.6.0) that automatically handles static asset copying, CSS injection, compile-time CESIUM_BASE_URL definition, and Ion token management. Designed specifically for the lightweight @cesium/engine package rather than the full cesium bundle. Key differentiators: no configuration needed for most cases, built-in .env support for per-environment Ion tokens, virtual module for runtime constants, and token validation. Release cadence: active with minor/patch updates every few months. Requires @cesium/engine >=11.0.0 and Vite >=5.0.0.

Common errors

error TypeError: cesiumEngine is not a function ↓

cause Default import used instead of named import.

fix

Change to import { cesiumEngine } from 'vite-plugin-cesium-engine'.

error Error: Cannot find module 'virtual:cesium' ↓

cause Virtual module not registered or plugin not added to vite config.

fix

Add the plugin in vite.config.ts: plugins: [cesiumEngine()]. The virtual module is only available inside Vite's module resolution.

error CesiumWidget: MISSING ASSETS - CESIUM_BASE_URL is not set ↓

cause Plugin not configured or assets not copied correctly.

fix

Ensure the plugin is added and you are using @cesium/engine. If using custom assetPath, verify the output directory.

Warnings

breaking CESIUM_BASE_URL handling changed in v1.5.0 – no longer sets window.CESIUM_BASE_URL, uses Vite's define instead. ↓

fix Update any runtime code that relied on window.CESIUM_BASE_URL; use the virtual:cesium module or plugin options if needed.

breaking CSP options removed in v1.5.0 (previously ignored anyway). ↓

fix Remove any CSP-related plugin options from your configuration.

gotcha Do not use default import for cesiumEngine – it's a named export. ↓

fix Use `import { cesiumEngine } from 'vite-plugin-cesium-engine'` instead of default import.

gotcha ionToken auto-detection from .env requires the variable to be loaded by Vite (must be prefixed with VITE_? No, it uses CESIUM_ION_TOKEN). ↓

fix Ensure your .env file defines CESIUM_ION_TOKEN or CESIUM_ION_TOKEN_<MODE> and that the file is in the project root. No VITE_ prefix needed.

deprecated Using the full 'cesium' package (not '@cesium/engine') is not supported; this plugin is designed for the modular engine only. ↓

fix Install @cesium/engine instead of cesium and update imports accordingly.

Install

npm install vite-plugin-cesium-engine

yarn add vite-plugin-cesium-engine

pnpm add vite-plugin-cesium-engine

Imports

cesiumEngine

wrong

import cesiumEngine from 'vite-plugin-cesium-engine'

correct

import { cesiumEngine } from 'vite-plugin-cesium-engine'

Named export only. Default import will cause 'undefined is not a function' error.

cesiumEngine

wrong

const cesiumEngine = require('vite-plugin-cesium-engine')

correct

const { cesiumEngine } = require('vite-plugin-cesium-engine')

CJS require must destructure the named export.

virtual:cesium
wrong
```
import { CESIUM_BASE_URL } from 'vite-plugin-cesium-engine'
```
correct
```
import { CESIUM_BASE_URL, CESIUM_VERSION } from 'virtual:cesium'
```
This is a virtual module provided by the plugin, not an export from the package itself. Types are included.
CesiumWidget
wrong
```
import { CesiumWidget } from 'cesium'
```
correct
```
import { CesiumWidget } from '@cesium/engine'
```
This plugin is for @cesium/engine only, not the full cesium package. Using the wrong import will cause missing assets.

Quickstart

Minimal setup: add the plugin to vite.config.ts, then import and instantiate CesiumWidget.

// vite.config.ts
import { defineConfig } from 'vite';
import { cesiumEngine } from 'vite-plugin-cesium-engine';

export default defineConfig({
  plugins: [cesiumEngine({
    // Optional: specify Ion token or let it read from .env
    ionToken: process.env.CESIUM_ION_TOKEN ?? '',
  })],
});

// app.ts
import { CesiumWidget } from '@cesium/engine';

const container = document.getElementById('cesium-container')!;
const widget = new CesiumWidget(container);