vite-plugin-cesium

1.2.23 verified Mon Apr 27 auth: no javascript

Vite plugin that simplifies integrating CesiumJS into Vite projects. Current stable version is 1.2.23, with active maintenance and frequent patches. It handles Cesium's static assets, worker files, and CSS, providing a seamless development experience. Key differentiators: no manual copy steps, configurable rebuildCesium option, and support for Cesium Ion SDK paths. Requires Cesium ^1.95.0 and Vite >=2.7.1.

Common errors

error Error: [vite-plugin-cesium] cesium is not a function ↓

cause Cesium version incompatibility with plugin versions <=1.2.20

fix

Upgrade vite-plugin-cesium to >=1.2.21 and cesium to ^1.96.0

error Error: Cannot find module 'cesium' or its corresponding type declarations. ↓

cause Missing cesium dependency or incorrect import path

fix

Run 'npm install cesium' and use import { Viewer } from 'cesium'

error Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "text/html". ↓

cause Missing or misconfigured base path for worker files (common when not using plugin)

fix

Use vite-plugin-cesium to automatically handle worker paths

error TypeError: Cannot read properties of undefined (reading 'default') ↓

cause Using require() with ESM-only Cesium

fix

Change to import * as Cesium from 'cesium' or import { Viewer } from 'cesium'

Warnings

breaking Cesium 1.96.0 introduced changes that broke earlier versions of this plugin; fixed in v1.2.21. ↓

fix Upgrade to vite-plugin-cesium >=1.2.21 and ensure cesium >=1.96.0.

gotcha On Windows, loading widgets.css may fail due to path resolution; fixed in v1.2.16. ↓

fix Update to >=1.2.16 or manually workaround path issues by using forward slashes.

gotcha The plugin is ESM-only; using require() will throw an error. ↓

fix Use import syntax: import cesium from 'vite-plugin-cesium';

deprecated Cesium is not a function error from v1.2.20 was a bug fixed in that same version. ↓

fix Upgrade to v1.2.21 or later.

gotcha If using rebuildCesium: true, the build output may exceed default chunk size warnings; plugin sets chunkSizeWarningLimit to 5000. ↓

fix Expect larger bundle size when rebuilding from source; adjust Vite's build.chunkSizeWarningLimit if needed.

Install

npm install vite-plugin-cesium

yarn add vite-plugin-cesium

pnpm add vite-plugin-cesium

Imports

default (cesium function)
wrong
```
const cesium = require('vite-plugin-cesium');
```
correct
```
import cesium from 'vite-plugin-cesium';
```
ESM-only; CommonJS require will fail. Use named export in ts if needed: import cesium from 'vite-plugin-cesium'.
Cesium.Viewer
wrong
```
import Viewer from 'cesium';
```
correct
```
import { Viewer } from 'cesium';
```
Cesium exports are named, not default. Use named imports for specific classes.
Cesium (global object)
wrong
```
const Cesium = require('cesium');
```
correct
```
import * as Cesium from 'cesium';
```
For accessing the entire Cesium namespace, use namespace import. CommonJS require may cause issues with static assets.

Quickstart

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"
}