vue-cesium

library3.2.12jsnpmunverified

Vue-Cesium is a comprehensive component library designed for seamlessly integrating CesiumJS into Vue 3 applications. It provides a rich set of Vue components that encapsulate core CesiumJS functionalities, simplifying the development of interactive 3D globes and maps. The current stable version is 3.2.12, with frequent beta releases indicating active development and a steady cadence of bug fixes and minor feature enhancements. Key differentiators include its full adoption of Vue 3's Composition API, its implementation in TypeScript for enhanced type safety, and its explicit compatibility with various Cesium-based platforms such as SuperMap iClient3D, Earth SDK, Mars3D, and DC-SDK, extending its utility beyond just the official CesiumJS library. This broad support makes it a versatile choice for diverse GIS development ecosystems.

web-framework data

npm install vue-cesium

package ↗homepage ↗

INSTALL

IMPORT

SIG · VUE-CESIUM

vue-cesium

web-frameworkjavascriptv3.2.12

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

VueCesium

✓ import VueCesium from 'vue-cesium'

✗ const VueCesium = require('vue-cesium')

Used for global plugin installation in Vue 3 applications. Vue-Cesium is ESM-only.

VcViewer

✓ import { VcViewer } from 'vue-cesium'

Main component for creating a Cesium viewer instance. Access components via named imports after global plugin registration.

VcViewerInstance

✓ import type { VcViewerInstance } from 'vue-cesium'

Type import for the viewer instance, useful for TypeScript projects.

This quickstart demonstrates how to set up a basic Vue 3 application with Vue-Cesium, including global plugin registration, CesiumJS asset imports, and a minimal `vc-viewer` component with a simple entity. It also shows how to set the Cesium Ion access token.

import { createApp } from 'vue'; import App from './App.vue'; import VueCesium from 'vue-cesium'; import 'vue-cesium/dist/index.css'; import * as Cesium from 'cesium'; import 'cesium/Build/Cesium/Widgets/widgets.css'; // Set your Cesium Ion default access token Cesium.Ion.defaultAccessToken = process.env.VITE_CESIUM_ION_ACCESS_TOKEN ?? 'YOUR_ION_ACCESS_TOKEN'; const app = createApp(App); app.use(VueCesium); app.mount('#app'); // App.vue // <template> // <div class="full-container"> // <vc-viewer :animation="true" :timeline="true" ref="vcViewerRef"> // <vc-entity :position="[105, 30, 100000]" description="Hello Vue-Cesium!"> // <vc-graphics-point :pixel-size="20" material="red"></vc-graphics-point> // <vc-graphics-label text="Vue-Cesium Example" :pixel-offset="[0, -50]" font="24px sans-serif"></vc-graphics-label> // </vc-entity> // </vc-viewer> // </div> // </template> // // <script setup lang="ts"> // import { onMounted, ref } from 'vue'; // // const vcViewerRef = ref(null); // // onMounted(() => { // if (vcViewerRef.value) { // console.log('VcViewer instance:', vcViewerRef.value.cesiumObject); // } // }); // </script> // // <style> // .full-container { // width: 100vw; // height: 100vh; // overflow: hidden; // } // </style>

Debug

Known issues

gotchaWhen integrating Vue-Cesium with CSS frameworks like Tailwind CSS, be aware that global utility classes such as `flex`, `row`, and `column` might conflict with Vue-Cesium's internal styles. As of v3.2.12, Vue-Cesium began prefixing its internal utility classes with `vc-` (e.g., `vc-flex`, `vc-row`) to mitigate these conflicts.

fix

If experiencing styling issues, check for class name conflicts. For versions >=3.2.12, ensure your CSS doesn't override `vc-` prefixed classes or adjust your framework's configuration to avoid collision. If using older versions, manual style overrides might be necessary.

affects: >=3.2.12

gotchaVue-Cesium components rely on a correctly configured CesiumJS environment. Issues may arise if the CesiumJS library or its assets (e.g., `widgets.css`) are not properly imported or made available to the build system, leading to rendering errors or missing UI elements.

fix

Ensure `import 'cesium/Build/Cesium/Widgets/widgets.css';` is included in your entry file. For applications using bundlers, configure webpack/vite to copy CesiumJS assets from `node_modules/cesium/Build/Cesium` to your build output directory, especially the `Assets`, `Widgets`, `Workers`, and `ThirdParty` folders.

affects: >=3.0.0

gotchaVue-Cesium depends on CesiumJS for its core functionality. Specific versions of Vue-Cesium are tested and optimized for particular CesiumJS versions. For instance, v3.2.9 introduced compatibility fixes for Cesium version 1.121. Running incompatible versions can lead to unexpected behavior or runtime errors.

fix

Always refer to the official Vue-Cesium documentation or changelog for recommended CesiumJS versions. When upgrading either library, test thoroughly and ensure compatibility, especially if experiencing new issues.

affects: >=3.0.0

Errors

Common errors & fixes

Failed to load Cesium.js assets.

CesiumJS requires several asset folders (Assets, Widgets, Workers, ThirdParty) to be accessible at runtime, typically copied to your project's public directory.

fix

Configure your build tool (e.g., Vite, Webpack) to copy the contents of `node_modules/cesium/Build/Cesium` to a public path. For Vite, you might use a plugin like `vite-plugin- cesium` or manual configuration in `vite.config.ts`. For Webpack, use `copy-webpack-plugin`.

Error: Cesium.Ion.defaultAccessToken must be defined. Visit https://cesium.com/ion/ for a free personal token.

The CesiumJS library requires an Ion access token for certain functionalities, such as loading base layers or terrain from Cesium Ion services.

fix

Obtain a free token from Cesium Ion (https://cesium.com/ion/) and set it in your application's entry file: `Cesium.Ion.defaultAccessToken = 'YOUR_ION_ACCESS_TOKEN';`.

[Vue warn]: Failed to resolve component: vc-viewer

The Vue-Cesium plugin has not been properly registered with your Vue application, or components are not being imported correctly.

fix

Ensure you are calling `app.use(VueCesium);` after creating your Vue app instance and before mounting it. Also, verify that named components (e.g., `VcViewer`) are imported explicitly if not relying on global component registration.

Upgrade

Version history

3.2.12latest on npm

Audit

Dependencies

vuerequiredRequired peer dependency for Vue 3.x applications.

Agent activity

31 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/vue-cesium ↗

homepagehttps://zouyaoji.github.io/vue-cesium ↗