NPM пакеты

Современная разработка геопространственных веб-приложений редко ограничивается подключением библиотек через тег <script>. Большинство проектов используют менеджеры пакетов, системы сборки и модульную архитектуру. В экосистеме CesiumJS центральное место занимает менеджер пакетов NPM (Node Package Manager), который позволяет устанавливать, обновлять и интегрировать библиотеку в современные JavaScript-проекты.

Использование NPM обеспечивает:

  • управление версиями CesiumJS;
  • автоматическую установку зависимостей;
  • интеграцию с Webpack, Vite, Rollup и другими сборщиками;
  • поддержку модульного импорта;
  • удобное обновление библиотек;
  • воспроизводимость окружения между разработчиками и серверами.

Что такое NPM

NPM представляет собой стандартный менеджер пакетов для платформы Node.js. Он состоит из двух основных компонентов:

  1. Онлайн-репозиторий пакетов.
  2. Утилита командной строки для работы с пакетами.

После установки Node.js команда npm становится доступной в терминале.

Проверка установки:

node -v
npm -v

Пример результата:

v22.5.1
10.8.2

Установка CesiumJS через NPM

Для подключения библиотеки в существующий проект используется команда:

npm install cesium

После завершения установки в каталоге проекта появится директория:

node_modules/

Внутри неё будет находиться пакет:

node_modules/cesium

Также автоматически обновится файл:

package.json

Пример записи:

{
  "dependencies": {
    "cesium": "^1.133.0"
  }
}

Создание нового проекта

Перед установкой библиотеки обычно инициализируется проект.

Создание проекта:

npm init -y

Будет создан файл:

{
  "name": "cesium-project",
  "version": "1.0.0"
}

После этого можно устанавливать любые зависимости.

Установка CesiumJS:

npm install cesium

Структура пакета Cesium

После установки пакет содержит большое количество файлов.

Упрощённая структура:

node_modules/
└── cesium/
    ├── Build/
    ├── Source/
    ├── Widgets/
    ├── ThirdParty/
    ├── package.json
    └── index.cjs

Наиболее важные каталоги:

Каталог Назначение
Build Готовые собранные версии библиотеки
Source Исходный код CesiumJS
Widgets Стандартные виджеты интерфейса
ThirdParty Сторонние зависимости
Assets Изображения, шрифты и служебные данные

Импорт CesiumJS

После установки пакет можно импортировать как обычный JavaScript-модуль.

Полный импорт:

import * as Cesium from "cesium";

Создание Viewer:

import * as Cesium from "cesium";

const viewer = new Cesium.Viewer("cesiumContainer");

Такой подход является наиболее распространённым.

Импорт отдельных компонентов

Cesium предоставляет возможность импортировать отдельные сущности.

Пример:

import {
    Viewer,
    Cartesian3,
    Color
} from "cesium";

Использование:

const viewer = new Viewer("cesiumContainer");

viewer.entities.add({
    position: Cartesian3.fromDegrees(30, 50),
    point: {
        pixelSize: 10,
        color: Color.RED
    }
});

Подобный стиль делает код более читаемым.

Установка конкретной версии

Для долгосрочных проектов важно фиксировать версии библиотек.

Установка определённой версии:

npm install cesium@1.120.0

После установки:

{
  "dependencies": {
    "cesium": "1.120.0"
  }
}

Фиксация версии позволяет избежать неожиданных изменений после обновлений.

Обновление Cesium

Просмотр устаревших пакетов:

npm outdated

Обновление Cesium:

npm update cesium

Установка последней версии:

npm install cesium@latest

Проверка установленной версии:

npm list cesium

Результат:

└── cesium@1.133.0

Удаление пакета

Удаление библиотеки:

npm uninstall cesium

После выполнения команды пакет удаляется из:

node_modules

и из списка зависимостей в package.json.

Зависимости и DevDependencies

В NPM существуют два основных типа зависимостей.

Dependencies

Используются приложением во время выполнения.

Пример:

npm install cesium

Запись:

{
  "dependencies": {
    "cesium": "^1.133.0"
  }
}

DevDependencies

Используются только на этапе разработки.

Пример:

npm install vite --save-dev

Результат:

{
  "devDependencies": {
    "vite": "^7.0.0"
  }
}

Типичная конфигурация проекта Cesium:

{
  "dependencies": {
    "cesium": "^1.133.0"
  },
  "devDependencies": {
    "vite": "^7.0.0"
  }
}

Использование package-lock.json

После установки пакетов автоматически создаётся файл:

package-lock.json

Он хранит точные версии всех зависимостей.

Пример:

{
  "name": "project",
  "lockfileVersion": 3
}

Файл позволяет:

  • получать одинаковые версии на всех компьютерах;
  • избегать конфликтов между разработчиками;
  • обеспечивать воспроизводимость сборок.

В системах контроля версий его обычно сохраняют вместе с проектом.

Команда npm install

После клонирования проекта из репозитория достаточно выполнить:

npm install

NPM автоматически:

  1. прочитает package.json;
  2. загрузит все зависимости;
  3. создаст каталог node_modules;
  4. восстановит структуру проекта.

Это стандартный способ подготовки окружения.

Использование npm ci

Для серверов непрерывной интеграции чаще применяется команда:

npm ci

Особенности:

  • работает быстрее;
  • использует только package-lock.json;
  • гарантирует одинаковые версии пакетов.

Такой подход широко применяется в производственных системах.

Скрипты NPM

В файле package.json можно описывать команды проекта.

Пример:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

Запуск:

npm run dev

Сборка:

npm run build

Предпросмотр:

npm run preview

Подобная организация делает процесс разработки единообразным.

Cesium и Vite

На сегодняшний день Vite является одним из наиболее популярных инструментов для работы с CesiumJS.

Установка:

npm install vite --save-dev
npm install cesium

Структура проекта:

project/
├── public/
├── src/
├── package.json
├── vite.config.js
└── index.html

Создание приложения:

import * as Cesium from "cesium";

const viewer = new Cesium.Viewer("cesiumContainer");

Запуск:

npm run dev

Cesium и Webpack

До появления Vite большинство проектов использовало Webpack.

Установка:

npm install webpack webpack-cli --save-dev
npm install cesium

Преимущества Webpack:

  • гибкая конфигурация;
  • поддержка множества плагинов;
  • зрелая экосистема.

Недостатком является более сложная настройка по сравнению с Vite.

Работа с ресурсами Cesium

Cesium использует большое количество дополнительных файлов:

  • изображения;
  • шрифты;
  • Web Worker-файлы;
  • шейдеры;
  • данные виджетов.

По этой причине недостаточно просто импортировать пакет.

Во многих конфигурациях необходимо корректно настроить путь к ресурсам:

window.CESIUM_BASE_URL = "/cesium/";

или

import { buildModuleUrl } from "cesium";

buildModuleUrl.setBaseUrl("/cesium/");

Неверная настройка приводит к ошибкам загрузки Worker-файлов и интерфейсных ресурсов.

Использование NPX

Утилита npx входит в состав NPM и позволяет запускать пакеты без глобальной установки.

Пример создания проекта Vite:

npm create vite@latest

или

npx create-vite

После генерации проекта можно установить Cesium:

npm install cesium

Семантическое версионирование

Большинство пакетов NPM используют схему:

MAJOR.MINOR.PATCH

Например:

1.133.0

Где:

  • MAJOR — несовместимые изменения;
  • MINOR — новая функциональность;
  • PATCH — исправления ошибок.

Пример:

{
  "dependencies": {
    "cesium": "^1.133.0"
  }
}

Символ ^ означает возможность установки новых MINOR и PATCH-версий.

Полезные команды NPM для проектов CesiumJS

Проверка версии пакета:

npm list cesium

Просмотр всех зависимостей:

npm list

Проверка уязвимостей:

npm audit

Автоматическое исправление:

npm audit fix

Просмотр информации о пакете:

npm info cesium

Очистка кэша:

npm cache clean --force

Удаление всех пакетов:

rm -rf node_modules

Повторная установка:

npm install

Типовая конфигурация проекта CesiumJS

Пример файла package.json для современного приложения:

{
  "name": "cesium-app",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "cesium": "^1.133.0"
  },
  "devDependencies": {
    "vite": "^7.0.0"
  }
}

Такая структура обеспечивает удобную разработку, контроль версий зависимостей, воспроизводимость сборок и полноценную интеграцию CesiumJS в современную JavaScript-инфраструктуру.

Оглавление