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
muslnode 18–223 runs
build_error
glibcnode 18–223 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
default (cesium function)
✓ import cesium from 'vite-plugin-cesium';
✗ const cesium = require('vite-plugin-cesium');
ESM-only; CommonJS require will fail. Use named export in ts if needed: import cesium from 'vite-plugin-cesium'.
Cesium.Viewer
✓ import { Viewer } from 'cesium';
✗ import Viewer from 'cesium';
Cesium exports are named, not default. Use named imports for specific classes.
Cesium (global object)
✓ import * as Cesium from 'cesium';
✗ const Cesium = require('cesium');
For accessing the entire Cesium namespace, use namespace import. CommonJS require may cause issues with static assets.
Minimal setup: add plugin to vite.config.js, import Viewer from cesium, create HTML container, and run dev/build.
// vite.config.js
import { defineConfig } from 'vite';
import cesium from 'vite-plugin-cesium';
export default defineConfig({
plugins: [cesium()]
});
// src/index.js
import { Viewer } from 'cesium';
import './css/main.css';
const viewer = new Viewer('cesiumContainer');
// index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<script type="module" src="/src/index.js"></script>
</head>
<body>
<div id="cesiumContainer"></div>
</body>
</html>
// package.json scripts
"scripts": {
"dev": "vite",
"build": "vite build"
}
Errors
Common errors & fixes
Error: [vite-plugin-cesium] cesium is not a function
Cesium version incompatibility with plugin versions <=1.2.20
fixUpgrade vite-plugin-cesium to >=1.2.21 and cesium to ^1.96.0
Error: Cannot find module 'cesium' or its corresponding type declarations.
Missing cesium dependency or incorrect import path
fixRun 'npm install cesium' and use import { Viewer } from 'cesium' Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "text/html".
Missing or misconfigured base path for worker files (common when not using plugin)
fixUse vite-plugin-cesium to automatically handle worker paths
TypeError: Cannot read properties of undefined (reading 'default')
Using require() with ESM-only Cesium
fixChange to import * as Cesium from 'cesium' or import { Viewer } from 'cesium' Audit
Dependencies
cesiumrequiredPeer dependency: core Cesium library required for functionality
viterequiredPeer dependency: plugin for Vite build tool