vite-plugin-cesium-build

0.7.4 verified Mon Apr 27 auth: no javascript

A Vite plugin for integrating CesiumJS into Vite projects. It externalizes Cesium.js and its CSS, copies the Cesium static assets to the output directory, and sets CESIUM_BASE_URL automatically. Current stable version is 0.7.4, supports Vite 5 through 8, and ships TypeScript types. Compared to other Cesium Vite plugins (e.g., vite-plugin-cesium), this plugin offers faster builds by not processing Cesium through Vite's bundler, supports @cesium/engine, and provides fine-grained control via options like iife, css, customCesiumBaseUrl.

Common errors

error Error: ENOTDIR: not a directory, scandir 'node_modules/cesium/Build/Cesium' ↓

cause The default 'from' path points to 'node_modules/cesium/Build/Cesium', but the actual Cesium package might be located elsewhere (e.g., cesium/Build/Cesium with different casing).

fix

Set the 'from' option to the correct path where Cesium's Build/Cesium folder exists, e.g., cesium({ from: 'node_modules/cesium/Build/Cesium' })

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

cause Using wrong import path or named import instead of default for the plugin function.

fix

Use import cesium from 'vite-plugin-cesium-build' (default import) instead of import { cesium } from 'vite-plugin-cesium-build'.

error Cesium is not defined ↓

cause When iife:true (default), Cesium is injected as a global via IIFE in index.html. If the script fails to load or is blocked, Cesium will be undefined.

fix

Ensure the Cesium static assets (Cesium.js, widgets.css) are copied correctly to the output directory and the script tag is present in index.html. Check network tab for 404 errors.

error Module not found: Error: Can't resolve 'vite-plugin-cesium-build/engine' ↓

cause Trying to use the engine subpath without having @cesium/engine installed, or the plugin version is too old (<0.4.0).

fix

Install @cesium/engine and ensure you are using vite-plugin-cesium-build >=0.4.0.

Warnings

breaking In v0.5.0, the copy logic and imports were improved, potentially breaking custom setups using core methods. ↓

fix If using core methods (imports, setBaseUrl), review the changes in v0.5.0 and adjust your configuration.

breaking In v0.5.0, crossorigin attribute is now used in production for script tags, which may cause CORS issues if your Cesium assets are on a different origin. ↓

fix Ensure your Cesium assets are served with appropriate CORS headers, or set customCesiumBaseUrl to handle cross-origin manually.

gotcha When iife:false, Cesium is not automatically added to index.html; you must import Cesium modules manually via ES imports. ↓

fix Set iife:true (default) for automatic script injection, or manually import Cesium in your application code if iife:false.

deprecated The css option was introduced in v0.4.4 and may be deprecated in future versions in favor of automatic detection. ↓

fix Always set css:true if you want Cesium CSS to be included. In future, the plugin may auto-detect.

gotcha Using vite-plugin-cesium-build with @cesium/engine requires importing from 'vite-plugin-cesium-build/engine', not the default path. ↓

fix Use `import cesium from 'vite-plugin-cesium-build/engine'` when your project uses @cesium/engine.

Install

npm install vite-plugin-cesium-build

yarn add vite-plugin-cesium-build

pnpm add vite-plugin-cesium-build

Imports

default (cesium function)
wrong
```
import { cesium } from 'vite-plugin-cesium-build'
```
correct
```
import cesium from 'vite-plugin-cesium-build'
```
Default export of the plugin function for standard CesiumJS package.

default (engine function)

wrong

import { cesium } from 'vite-plugin-cesium-build'

correct

import cesium from 'vite-plugin-cesium-build/engine'

Use this subpath when using @cesium/engine. Exported as default.

imports, setBaseUrl

wrong

import { imports, setBaseUrl } from 'vite-plugin-cesium-build'

correct

import { imports, setBaseUrl } from 'vite-plugin-cesium-build/core'

Core utilities for custom setups. Only available from 'vite-plugin-cesium-build/core'.

Quickstart

Shows the minimal setup to add CesiumJS support to a Vite project using the default plugin.

import { defineConfig } from 'vite';
import cesium from 'vite-plugin-cesium-build';

export default defineConfig({
  plugins: [cesium()],
});