{"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,"search_vec":"'11.0.0':84 '3d':95 '5.0.0':87 'activ':75 'asset':18 'automat':15 'base':26 'built':55 'built-in':54 'bundl':45 'cadenc':74 'case':53 'cesium':4,25,44,93 'cesium/engine':12,38,83,94 'compil':23 'compile-tim':22 'config':8 'configur':49 'constant':69 'copi':19 'css':20 'definit':28 'design':33 'differenti':47 'engin':5 'env':57 'environ':62 'everi':79 'full':43 'handl':16 'inject':21 'ion':30,63 'javascript':88 'key':46 'lightweight':37 'manag':32 'minor/patch':77 'modul':66 'month':81 'need':50 'packag':39 'per':61 'per-environ':60 'plugin':3,10,92 'rather':40 'releas':73 'requir':82 'runtim':68 'specif':34 'static':17 'support':58 'time':24 'token':31,64,71 'typescript':96 'updat':78 'url':27 'v1.6.0':13 'valid':72 'virtual':65 'vite':2,9,86,89,91 'vite-plugin':90 'vite-plugin-cesium-engin':1 'zero':7 'zero-config':6","created_at":"2026-04-27T17:06:03.233630+00:00","updated_at":"2026-04-27T17:06:03.233630+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/jfayot/vite-plugin-cesium-engine","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vite-plugin-cesium-engine","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-18","next_check":"2026-07-26","install_tag":null}}