create-cesiumjs

CesiumJS Project Starter

Create a production-ready CesiumJS geospatial visualization project in seconds with npm create cesiumjs (or npm init cesiumjs—both work!). This official-style starter automates project setup, dependency installation, and Cesium asset configuration, supporting HTML (no framework), Vue3 + Vite, and React18 + Vite templates.

Quick Start

Get a CesiumJS project running in 3 steps:

• Initialize the project
  Run one of the following commands (they’re identical in functionality):

  # Using "create" (modern npm convention)
  npm create cesiumjs@latest
  
  # Or using "init" (legacy-compatible)
  npm init cesiumjs@latest
  

• Answer the prompts
  The CLI will guide you through setup with simple questions:

  • Project name: Defaults to cesiumjs-project (press Enter to use, or type a custom name).
  • Template selection: Choose from:
    • HTML (No framework, pure frontend demo)
    • Vue3 + Vite (Component-based development)
    • React18 + Vite (Component-based development)
  • Cesium version: Use latest (default) or specify a version (e.g., 1.117.0).
  • Install dependencies now?: Select Yes (default) to auto-install, or No for manual setup.

• Run the project
  Navigate to your project folder and start the development server:

  # Enter the project directory
  cd your-project-name
  
  # Start the dev server (works for all templates)
  npm run dev
  

Open http://localhost:5173 (Vite’s default port) in your browser—you’ll see a 3D Cesium globe ready to customize!

What You Get

Every project generated by npm create cesiumjs includes:

• A optimized project structure (tailored to your template).
• Pre-installed dependencies (CesiumJS + framework/Vite tools).
• Auto-copied Cesium assets (Workers, Widgets, terrain/imagery configs) in public/cesium/.
• A working demo: A basic Cesium Viewer with sample terrain (no empty "blank screen"!).
• Production-ready scripts (npm run build, npm run preview).

Project Structure

The starter generates a clean, maintainable structure based on your template choice. Below are examples for each supported stack:

1. HTML Template (No Framework)

Best for quick prototypes or vanilla JS projects:

your-project-name/
├── public/
│   └── cesium/          # Cesium core assets (auto-copied)
│       ├── Assets/      # Terrain, imagery, and 3D models
│       ├── ThirdParty/  # Dependencies like require.js
│       ├── Workers/     # Background processing scripts
│       ├── Widgets/     # UI controls (zoom, timeline, etc.)
│       ├── Cesium.js    # CesiumJS UMD bundle
│       └── index.js     # CesiumJS ES module entry
├── index.html           # Main file (Cesium Viewer initialized here)
├── package.json         # Dependencies + scripts
└── README.md            # Project docs (customized for your template)

2. Vue3 + Vite Template

For component-based Vue projects (includes vite-plugin-cesium for optimization):

your-project-name/
├── public/
│   └── cesium/          # Cesium assets (auto-configured)
├── src/
│   ├── components/
│   │   └── CesiumMap.vue # Reusable Cesium Viewer component
│   ├── main.js          # Vue entry (mounts App)
│   └── App.vue          # Root component (uses CesiumMap)
├── index.html
├── package.json
├── vite.config.js       # Vite + Cesium plugin config (pre-setup)
└── README.md

3. React18 + Vite Template

For React projects (optimized for React’s component model):

your-project-name/
├── public/
│   └── cesium/          # Cesium assets (auto-configured)
├── src/
│   ├── components/
│   │   └── CesiumMap.jsx # Reusable Cesium Viewer component
│   ├── main.jsx         # React entry (renders App)
│   └── App.jsx          # Root component (uses CesiumMap)
├── index.html
├── package.json
├── vite.config.js       # Vite + Cesium plugin config (pre-setup)
└── README.md

Critical Step: Add Your Cesium Ion Token

CesiumJS requires an Ion Token to access cloud-based terrain, imagery (e.g., Bing Maps), and 3D models. Here’s how to set it up:

• Get a free token

  • Go to Cesium Ion and sign up for a free account.
  • From your Cesium Ion dashboard, go to Access Tokens (under your profile).
  • Use the "Default Token" (pre-configured for basic terrain/imagery) or create a new token.

• Add the token to your project
  The starter includes a YOUR_CESIUM_ION_TOKEN placeholder in your code—replace it with your real token:

  Template	Where to Replace the Token
  HTML	In index.html (search for Cesium.Ion.defaultAccessToken)
  Vue3	In src/components/CesiumMap.vue
  React18	In src/components/CesiumMap.jsx

  Example (HTML template):

  // Before (placeholder)
  Cesium.Ion.defaultAccessToken = "YOUR_CESIUM_ION_TOKEN";
  
  // After (with real token)
  Cesium.Ion.defaultAccessToken = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."; // Your token here
  

NPM Scripts

All generated projects include standardized scripts in package.json—use them for every development workflow:

Script	Purpose
npm run dev	Start the development server (auto-reloads on code changes).
npm run build	Build the project for production (optimized, minified assets).
npm run preview	Preview the production build locally (before deploying).
npm run clean	Delete the dist/ folder (production builds) and node_modules/.cache

Troubleshooting

1. "Command not found: npm create cesiumjs"

• Cause: Your npm version is outdated (needs npm 6+ for npm init or npm 7+ for npm create).
• Fix: Update npm first:

  npm install -g npm@latest
  

  Then re-run npm create cesiumjs@latest.

2. Cesium assets fail to load (404 errors)

• Cause: The starter auto-copies Cesium assets to public/cesium/—if this step was skipped (e.g., manual dependency install), assets will be missing.
• Fix: Run the asset copy script (included in all projects):

  npm run copy:cesium-assets
  

3. "Cesium is not defined" (Vue/React)

• Cause: Missing import or incorrect Cesium configuration in Vite.
• Fix: The starter includes vite-plugin-cesium (pre-configured in vite.config.js). Ensure you’re using the generated CesiumMap component— it includes the correct imports:

  // Vue example (src/components/CesiumMap.vue)
  import { Viewer } from 'cesium';
  import 'cesium/Build/Cesium/Widgets/widgets.css';
  

Customization Tips

• Add terrain/imagery: Use Cesium Ion’s asset library (e.g., add "Cesium World Imagery" by updating the assetId in your viewer code).
• Integrate 3D models: Upload glTF models to Cesium Ion, then load them into your viewer with Cesium.IonResource.fromAssetId().
• Add interactions: Extend the demo with Cesium’s APIs (e.g., viewer.entities.add() to draw points/lines, viewer.camera.flyTo() to navigate to locations).

Dependencies

The starter automatically installs all required dependencies based on your template:

Template	Core Dependencies
HTML	cesium, serve (for static file serving)
Vue3 + Vite	cesium, vue@^3.4.0, vite@^5.0.0, @vitejs/plugin-vue, vite-plugin-cesium
React18 + Vite	cesium, react@^18.2.0, react-dom@^18.2.0, vite@^5.0.0, @vitejs/plugin-react, vite-plugin-cesium

Learn More

• CesiumJS Docs: Official CesiumJS Documentation (APIs, tutorials, and examples).
• Cesium Ion: Cesium Ion Dashboard (manage terrain, imagery, and 3D assets).
• Vite Config: Vite + Cesium Guide (optimize Cesium for production builds).

For bug reports or feature requests, visit the CesiumJS Starter Git Repository (fictional link for documentation purposes).