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

Driver.js распространяется как npm-пакет, поэтому установка через менеджер пакетов yarn является стандартным и предпочтительным способом интеграции библиотеки в проект.

Добавление зависимости

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

yarn add driver.js

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

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

После установки важно убедиться, что библиотека корректно добавлена в проект:

{
  "dependencies": {
    "driver.js": "^1.x.x"
  }
}

Фактическая версия может отличаться в зависимости от актуального релиза.

Импорт библиотеки

После установки библиотека доступна для использования в коде. В зависимости от используемой системы модулей применяются разные способы импорта.

ES Modules (рекомендуемый вариант)

import Driver from "driver.js";
import "driver.js/dist/driver.css";

CommonJS

const Driver = require("driver.js");
require("driver.js/dist/driver.css");

Подключение CSS-файла обязательно, так как он содержит стили для подсветки элементов и отображения всплывающих подсказок.

Особенности работы с Yarn

Yarn обеспечивает:

  • Быструю установку зависимостей за счёт кэширования
  • Детерминированность зависимостей через yarn.lock
  • Удобное управление версиями пакетов

При использовании монорепозиториев или workspaces установка может происходить на уровне корневого проекта:

yarn workspace my-app add driver.js

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

Иногда требуется зафиксировать определённую версию библиотеки:

yarn add driver.js@1.0.0

Это может быть необходимо при:

  • использовании стабильной версии в продакшене
  • несовместимости с более новыми релизами
  • повторяемости сборок

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

Для удаления пакета используется команда:

yarn remove driver.js

После удаления запись автоматически исчезает из package.json, а файлы удаляются из node_modules.

Обновление версии

Для обновления до последней версии:

yarn upgrade driver.js

Либо до конкретной:

yarn upgrade driver.js@latest

Работа с TypeScript

Driver.js не всегда содержит встроенные типы (в зависимости от версии). При необходимости используются дополнительные типы:

yarn add -D @types/driver.js

Если типы отсутствуют в DefinitelyTyped, допускается создание собственных деклараций:

declare module "driver.js";

Интеграция в сборщики

После установки через yarn библиотека автоматически включается в сборку при использовании:

  • Webpack
  • Vite
  • Rollup
  • Parcel

Важно учитывать:

  • CSS должен быть обработан соответствующим loader’ом (например, css-loader в Webpack)
  • при использовании Vite импорт CSS работает «из коробки»

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

При использовании Docker или CI/CD:

yarn install --frozen-lockfile

Это гарантирует установку строго зафиксированных версий зависимостей из yarn.lock.

Offline-установка

Yarn поддерживает оффлайн-режим при наличии кэша:

yarn install --offline

Это актуально для:

  • защищённых сетей
  • CI-сред
  • разработки без доступа к интернету

Использование с CDN как альтернатива

Хотя установка через yarn является основным способом, в некоторых случаях (например, прототипирование) допускается использование CDN. Однако при полноценной разработке предпочтительна именно пакетная установка через менеджер зависимостей.

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

После установки в node_modules/driver.js доступны:

  • основной JS-файл библиотеки
  • CSS-файлы
  • дополнительные ресурсы

Пример:

node_modules/
└── driver.js/
    ├── dist/
    │   ├── driver.js
    │   └── driver.css
    └── package.json

Контроль версий через yarn.lock

Файл yarn.lock фиксирует точные версии зависимостей, включая транзитивные. Это гарантирует:

  • идентичные сборки на разных машинах
  • отсутствие неожиданных обновлений
  • стабильность работы проекта

Изменения в yarn.lock должны отслеживаться системой контроля версий.

Ошибки при установке и их причины

Проблема: пакет не устанавливается Причины:

  • отсутствие доступа к registry
  • конфликт версий
  • повреждённый кэш

Решение:

yarn cache clean
yarn install

Проблема: CSS не применяется Причины:

  • отсутствует импорт CSS
  • неправильная конфигурация сборщика

Решение: проверить импорт:

import "driver.js/dist/driver.css";

Проблема: несовместимость версий Причины:

  • устаревшие зависимости
  • breaking changes в библиотеке

Решение: зафиксировать стабильную версию:

yarn add driver.js@<версия>

Рекомендации по использованию

  • использовать фиксированные версии для продакшена
  • хранить yarn.lock в репозитории
  • проверять изменения после обновления версии
  • подключать CSS сразу при импорте
Оглавление