Registry / web-framework / vite-plugin-cesium-engine

vite-plugin-cesium-engine

library1.6.0jsnpmunverified

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.

web-framework

npm install vite-plugin-cesium-engine

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-CESIUM

vite-plugin-cesium-engine

web-frameworkjavascriptv1.6.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

cesiumEngine

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

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

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

cesiumEngine

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

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

CJS require must destructure the named export.

virtual:cesium

✓ import { CESIUM_BASE_URL, CESIUM_VERSION } from 'virtual:cesium'

✗ import { CESIUM_BASE_URL } from 'vite-plugin-cesium-engine'

This is a virtual module provided by the plugin, not an export from the package itself. Types are included.

CesiumWidget

✓ import { CesiumWidget } from '@cesium/engine'

✗ import { CesiumWidget } from 'cesium'

This plugin is for @cesium/engine only, not the full cesium package. Using the wrong import will cause missing assets.

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);

Debug

Known issues

breakingCESIUM_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.

affects: >=1.5.0

breakingCSP options removed in v1.5.0 (previously ignored anyway).

fix

Remove any CSP-related plugin options from your configuration.

affects: >=1.5.0

gotchaDo not use default import for cesiumEngine – it's a named export.

fix

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

affects: >=1.0.0

gotchaionToken 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.

affects: >=1.0.0

deprecatedUsing 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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: cesiumEngine is not a function

Default import used instead of named import.

fix

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

Error: Cannot find module 'virtual:cesium'

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.

CesiumWidget: MISSING ASSETS - CESIUM_BASE_URL is not set

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.

Upgrade

Version history

1.6.0latest on npm

Audit

Dependencies

@cesium/enginerequiredpeer dependency – the Cesium engine library this plugin wraps

viterequiredpeer dependency – plugin only works within Vite >=5

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jfayot/vite-plugin-cesium-engine ↗

packagehttps://www.npmjs.com/package/vite-plugin-cesium-engine ↗