{"id":22603,"library":"vite-plugin-cesium-engine","title":"vite-plugin-cesium-engine","description":"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.","status":"active","version":"1.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/jfayot/vite-plugin-cesium-engine","tags":["javascript","vite","vite-plugin","cesium","@cesium/engine","3d","typescript"],"install":[{"cmd":"npm install vite-plugin-cesium-engine","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-cesium-engine","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-cesium-engine","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency – the Cesium engine library this plugin wraps","package":"@cesium/engine","optional":false},{"reason":"peer dependency – plugin only works within Vite >=5","package":"vite","optional":false}],"imports":[{"note":"Named export only. Default import will cause 'undefined is not a function' error.","wrong":"import cesiumEngine from 'vite-plugin-cesium-engine'","symbol":"cesiumEngine","correct":"import { cesiumEngine } from 'vite-plugin-cesium-engine'"},{"note":"CJS require must destructure the named export.","wrong":"const cesiumEngine = require('vite-plugin-cesium-engine')","symbol":"cesiumEngine","correct":"const { cesiumEngine } = require('vite-plugin-cesium-engine')"},{"note":"This is a virtual module provided by the plugin, not an export from the package itself. Types are included.","wrong":"import { CESIUM_BASE_URL } from 'vite-plugin-cesium-engine'","symbol":"virtual:cesium","correct":"import { CESIUM_BASE_URL, CESIUM_VERSION } from 'virtual:cesium'"},{"note":"This plugin is for @cesium/engine only, not the full cesium package. Using the wrong import will cause missing assets.","wrong":"import { CesiumWidget } from 'cesium'","symbol":"CesiumWidget","correct":"import { CesiumWidget } from '@cesium/engine'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport { cesiumEngine } from 'vite-plugin-cesium-engine';\n\nexport default defineConfig({\n  plugins: [cesiumEngine({\n    // Optional: specify Ion token or let it read from .env\n    ionToken: process.env.CESIUM_ION_TOKEN ?? '',\n  })],\n});\n\n// app.ts\nimport { CesiumWidget } from '@cesium/engine';\n\nconst container = document.getElementById('cesium-container')!;\nconst widget = new CesiumWidget(container);","lang":"typescript","description":"Minimal setup: add the plugin to vite.config.ts, then import and instantiate CesiumWidget."},"warnings":[{"fix":"Update any runtime code that relied on window.CESIUM_BASE_URL; use the virtual:cesium module or plugin options if needed.","message":"CESIUM_BASE_URL handling changed in v1.5.0 – no longer sets window.CESIUM_BASE_URL, uses Vite's define instead.","severity":"breaking","affected_versions":">=1.5.0"},{"fix":"Remove any CSP-related plugin options from your configuration.","message":"CSP options removed in v1.5.0 (previously ignored anyway).","severity":"breaking","affected_versions":">=1.5.0"},{"fix":"Use `import { cesiumEngine } from 'vite-plugin-cesium-engine'` instead of default import.","message":"Do not use default import for cesiumEngine – it's a named export.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"ionToken auto-detection from .env requires the variable to be loaded by Vite (must be prefixed with VITE_? No, it uses CESIUM_ION_TOKEN).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Install @cesium/engine instead of cesium and update imports accordingly.","message":"Using the full 'cesium' package (not '@cesium/engine') is not supported; this plugin is designed for the modular engine only.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Change to `import { cesiumEngine } from 'vite-plugin-cesium-engine'`.","cause":"Default import used instead of named import.","error":"TypeError: cesiumEngine is not a function"},{"fix":"Add the plugin in vite.config.ts: `plugins: [cesiumEngine()]`. The virtual module is only available inside Vite's module resolution.","cause":"Virtual module not registered or plugin not added to vite config.","error":"Error: Cannot find module 'virtual:cesium'"},{"fix":"Ensure the plugin is added and you are using @cesium/engine. If using custom assetPath, verify the output directory.","cause":"Plugin not configured or assets not copied correctly.","error":"CesiumWidget: MISSING ASSETS - CESIUM_BASE_URL is not set"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}