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

Библиотека распространяется через npm и подключается как стандартная зависимость JavaScript-проекта. Основной пакет устанавливается командой:

npm install tom-select

После установки пакет появляется в node_modules, а его метаданные фиксируются в package.json и package-lock.json. Это обеспечивает воспроизводимость сборки и одинаковое поведение зависимостей в разных окружениях.

Версионирование следует семантическому подходу. Обновления могут включать исправления, новые возможности или изменения API. Проверка установленной версии выполняется через:

npm list tom-select

или

npx tom-select --version

(если пакет доступен как исполняемый модуль в конкретной сборке).

Структура установленного пакета

После установки в node_modules/tom-select содержатся:

  • основной JavaScript-модуль
  • ESM-сборка (ES modules)
  • стили оформления
  • дополнительные вспомогательные файлы
  • типы TypeScript (в актуальных версиях)

Ключевые точки входа обычно представлены в package.json пакета через поля main и module, что позволяет сборщикам выбирать оптимальный формат подключения.

Подключение в проектах с ES Modules

В современных сборках (Vite, Webpack, Rollup) предпочтителен импорт через ES-модули:

import TomSelect from "tom-select";

После импорта класс TomSelect используется для инициализации селектов на DOM-элементах.

Дополнительно подключаются стили, так как логика и оформление разделены:

import "tom-select/dist/css/tom-select.css";

Отсутствие стилей приводит к корректной работе функционала без визуального оформления, что часто воспринимается как ошибка интеграции.

Использование в CommonJS окружении

В старых проектах или Node.js-сборках без ESM применяется CommonJS:

const TomSelect = require("tom-select").default;
require("tom-select/dist/css/tom-select.css");

Особенность заключается в наличии .default, так как пакет экспортируется как ES module, а CommonJS требует обращения к дефолтному экспорту через обёртку.

Подключение через сборщики модулей

Vite

Vite автоматически обрабатывает ESM:

import TomSelect from "tom-select";
import "tom-select/dist/css/tom-select.css";

Особенность Vite заключается в нативной поддержке ES модулей без дополнительной трансформации, что снижает накладные расходы при сборке.

Webpack

В Webpack требуется корректная настройка загрузчиков CSS:

import TomSelect from "tom-select";
import "tom-select/dist/css/tom-select.css";

Конфигурация должна включать обработку CSS через css-loader и style-loader, иначе стили не будут применены.

Rollup

При использовании Rollup важно учитывать оптимизацию tree-shaking:

import TomSelect from "tom-select";
import "tom-select/dist/css/tom-select.css";

Rollup корректно удаляет неиспользуемые части кода при правильной конфигурации плагинов @rollup/plugin-node-resolve и @rollup/plugin-commonjs.

Подключение TypeScript-типов

Пакет включает декларации типов, поэтому дополнительная установка @types обычно не требуется. Использование в TypeScript:

import TomSelect from "tom-select";

const sel ect = new TomSelect("#select", {
  create: true,
  persist: false
});

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

CSS-часть и необходимость стилей

Функциональность библиотеки разделена на логику и представление. CSS-файл:

tom-select/dist/css/tom-select.css

содержит:

  • базовую структуру выпадающего списка
  • стили активных элементов
  • оформление выбранных тегов
  • состояния hover и focus

Без подключения CSS поведение остаётся функциональным, но визуально компонент теряет читаемость и интерактивность.

Версии и управление обновлениями

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

npm install tom-select@2.3.0

Использование диапазонов версий в package.json:

{
  "dependencies": {
    "tom-select": "^2.3.0"
  }
}

Символ ^ фиксирует совместимость по мажорной версии, позволяя обновления минорных и патч-версий.

Кэширование и повторная установка

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

npm ci

Команда обеспечивает чистую установку на основе package-lock.json, удаляя старые версии и предотвращая расхождения зависимостей между средами.

Очистка и повторная сборка:

rm -rf node_modules
npm install

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

Типовые проверки после установки:

  • наличие каталога node_modules/tom-select
  • отсутствие ошибок импорта в сборщике
  • корректное подключение CSS
  • успешная инициализация экземпляра

Простейшая проверка инициализации:

import TomSelect fr om "tom-select";
import "tom-select/dist/css/tom-select.css";

new TomSelect("#select");

Особенности работы с ESM и CJS одновременно

Некоторые окружения требуют явного указания интероп-режима. Конфликт между форматами модулей может проявляться в:

  • undefined is not a constructor
  • ошибках импорта default

Решения зависят от сборщика:

  • включение esModuleInterop в TypeScript
  • настройка commonjs плагина в Rollup
  • корректный module режим в Webpack

Оптимизация размера бандла

Подключение через npm позволяет использовать tree-shaking. Для уменьшения размера итогового бандла:

  • импортируются только используемые части API
  • избегается дублирование CSS
  • исключаются неиспользуемые плагины и расширения

В некоторых случаях применяется динамический импорт:

import("tom-select").then(({ default: TomSelect }) => {
  new TomSelect("#select");
});

Поведение в серверных окружениях

При использовании SSR (например, Node.js рендеринг) важно учитывать отсутствие DOM. Инициализация выполняется только на клиенте:

if (typeof window !== "undefined") {
  import("tom-select").then(({ default: TomSelect }) => {
    new TomSelect("#select");
  });
}

Такой подход предотвращает ошибки document is not defined.

Совместимость с экосистемой npm

Библиотека корректно работает в стандартной npm-экосистеме:

  • React через useEffect и ref
  • Vue через mounted
  • Angular через lifecycle hooks
  • чистый JavaScript без фреймворков

Интеграция всегда начинается с npm-установки и последующего импорта модуля в контекст приложения.

Оглавление