create-cesiumjs/README.md

A scaffolding tool to quickly create CesiumJS geospatial visualization projects, supporting HTML, Vue3 + Vite, and React18 + Vite templates

# 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:  

1. **Initialize the project**  
   Run one of the following commands (they’re identical in functionality):  
   ```bash
   # Using "create" (modern npm convention)
   npm create cesiumjs@latest

   # Or using "init" (legacy-compatible)
   npm init cesiumjs@latest
   ```  

2. **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.  

3. **Run the project**  
   Navigate to your project folder and start the development server:  
   ```bash
   # 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:  

1. **Get a free token**  
   1. Go to [Cesium Ion](https://cesium.com/ion/) and sign up for a free account.  
   2. From your Cesium Ion dashboard, go to **Access Tokens** (under your profile).  
   3. Use the "Default Token" (pre-configured for basic terrain/imagery) or create a new token.  

2. **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):  
   ```javascript
   // 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:  
  ```bash
  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):  
  ```bash
  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:  
  ```javascript
  // 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](https://cesium.com/docs/cesiumjs-ref-doc/) (APIs, tutorials, and examples).  
- **Cesium Ion**: [Cesium Ion Dashboard](https://cesium.com/ion/) (manage terrain, imagery, and 3D assets).  
- **Vite Config**: [Vite + Cesium Guide](https://cesium.com/learn/cesiumjs-vite/) (optimize Cesium for production builds).  

For bug reports or feature requests, visit the [CesiumJS Starter Git Repository](https://gitee.com/cesiumjs/create-cesiumjs.git) (fictional link for documentation purposes).