Сборка из исходников

Shepherd.js можно собрать напрямую из исходного кода, что позволяет использовать последнюю версию библиотеки и подключать её с минимальными зависимостями. Исходники доступны в репозитории на GitHub. Для работы потребуется Node.js (рекомендуется версия 14 и выше) и пакетный менеджер npm или yarn.

Клонирование репозитория

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

git clone https://github.com/shipshapecode/shepherd.git
cd shepherd

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

Установка зависимостей

Shepherd.js использует современные инструменты сборки, такие как Rollup и PostCSS. Установка всех зависимостей производится командой:

npm install

или, если используется yarn:

yarn install

Это установит все пакеты, указанные в package.json, включая зависимости для сборки, тестирования и линтинга.

Сборка библиотеки

Shepherd.js использует Rollup для упаковки модулей. После установки зависимостей можно собрать библиотеку в продакшен-формате:

npm run build

Эта команда создаст директорию dist, где будут находиться:

  • shepherd.js — полный модуль с ES и UMD поддержкой,
  • shepherd.css — стили для подсказок,
  • shepherd.min.js — минифицированная версия скрипта.

Файлы в dist можно подключать напрямую в проект через <script> или импортировать как модули.

Настройка сборки под свои нужды

В rollup.config.js задаются конфигурации сборки:

  • input — путь к основному файлу библиотеки (src/js/index.js),
  • output — настройки форматов экспорта (ESM, UMD),
  • plugins — плагины Rollup для трансформации кода, обработки CSS и оптимизации.

Можно добавлять свои плагины, например, для поддержки TypeScript или добавления минификации CSS.

Разработка и локальная проверка

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

npm run dev

Она запускает сборку в режиме watch, автоматически пересобирая скрипт при изменении исходного кода. Пример HTML-файла для тестирования подсказок может быть расположен в папке examples:

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="../dist/shepherd.css">
</head>
<body>
  <button id="start-tour">Начать тур</button>
  <script src="../dist/shepherd.js"></script>
  <script>
    const tour = new Shepherd.Tour({
      defaultStepOptions: {
        cancelIcon: {
          enabled: true
        },
        scrollTo: { beh * avior: 'smooth', block: 'center' }
      }
    });

    tour.addStep({
      title: 'Пример шага',
      text: 'Это первый шаг вашего тура.',
      attachTo: { element: '#start-tour', on: 'bottom' }
    });

    document.getElementById('start-tour').addEventListener('click', () => {
      tour.start();
    });
  </script>
</body>
</html>

Создание кастомного билда

Shepherd.js поддерживает подключение отдельных модулей. Например, можно собрать версию без CSS или без некоторых плагинов:

  1. Отключить ненужные импорты в src/js/index.js.
  2. Изменить конфигурацию Rollup для включения только нужных плагинов.
  3. Выполнить сборку командой npm run build.

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

Тестирование сборки

После сборки рекомендуется проверять работу библиотеки с помощью встроенных тестов:

npm run test

Shepherd.js использует Jest и Puppeteer для юнит-тестов и тестирования взаимодействий с DOM. Тесты помогают убедиться, что кастомные сборки не ломают ключевые функции, такие как навигация между шагами, отображение подсказок и обработка событий.

Публикация кастомного билда

Для локального использования достаточно подключить файлы из dist. Для публикации на npm или внутри внутреннего проекта:

npm publish --access public

Перед этим важно обновить version в package.json и убедиться, что все файлы корректно включены в пакет через поле files.

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

Оглавление