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

Библиотека Interact.js представляет собой модульную систему, в которой различные возможности взаимодействия с элементами реализованы как независимые модули. Основные функции библиотеки — drag-and-drop, resizable, gestures, autoScroll, inertia, modifiers — построены поверх общего ядра событийной системы.

Исходный код проекта разделён на несколько логических уровней:

Ядро библиотеки

Ядро отвечает за:

  • обработку событий указателя (Pointer Events, Mouse Events, Touch Events)
  • управление интерактивными объектами
  • маршрутизацию событий
  • систему модификаторов
  • жизненный цикл взаимодействия

Ключевые концепции ядра:

Interactable — объект, описывающий элемент DOM и его возможности взаимодействия.

Interaction — конкретная активная сессия взаимодействия (например, текущее перетаскивание).

Action — тип действия:

  • drag
  • resize
  • gesture

Modifier — функция, изменяющая параметры взаимодействия (ограничения, снаппинг, границы).

Модульная структура

Исходники организованы по директориям:

packages/
    core/
    actions/
        drag/
        resize/
        gesture/
    modifiers/
        snap/
        restrict/
        restrictEdges/
        restrictSize/
    utils/
    inertia/
    auto-scroll/

Каждый модуль подключается к ядру через систему plugin registration.

Пример подключения модуля:

import interact from '@interactjs/interact'
import resize from '@interactjs/actions/resize'

interact.use(resize)

Внутри плагина регистрируются:

  • новые типы действий
  • обработчики событий
  • модификаторы

Инструменты сборки

Проект Interact.js использует современный стек сборки Jav * aScript:

Основные инструменты:

  • TypeScript
  • Rollup
  • Babel
  • ESLint
  • Prettier
  • Yarn / npm

Rollup применяется для создания различных вариантов сборки:

  • ESM
  • CommonJS
  • UMD
  • минифицированная версия

Типичная схема сборки:

TypeScript → Babel → Rollup → dist/

Подготовка окружения для сборки

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

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

git clone https://github.com/taye/interact.js
cd interact.js

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

npm install

или

yarn install

После установки формируется структура:

node_modules/
packages/
scripts/
rollup.config.js
tsconfig.json

Конфигурация TypeScript

Исходный код Interact.js написан на TypeScript, что обеспечивает:

  • строгую типизацию
  • автодополнение
  • контроль API
  • более безопасный рефакторинг

Основные настройки находятся в файле:

tsconfig.json

Пример ключевых параметров:

{
  "compilerOptions": {
    "target": "ES2017",
    "module": "ESNext",
    "declaration": true,
    "sourceMap": true,
    "strict": true,
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

Параметры означают:

Параметр Назначение
target версия ECMAScript
module формат модулей
declaration генерация .d.ts
sourceMap карты исходников
strict строгая типизация

Конфигурация Rollup

Rollup используется для создания финальных пакетов библиотеки.

Файл конфигурации:

rollup.config.js

Пример базовой конфигурации:

import typescript from '@rollup/plugin-typescript'
import babel from '@rollup/plugin-babel'
import { terser } from 'rollup-plugin-terser'

export default {
  input: 'packages/interactjs/index.ts',
  output: [
    {
      file: 'dist/interact.js',
      format: 'umd',
      name: 'interact'
    },
    {
      file: 'dist/interact.min.js',
      format: 'umd',
      name: 'interact',
      plugins: [terser()]
    },
    {
      file: 'dist/interact.esm.js',
      format: 'esm'
    }
  ],
  plugins: [
    typescript(),
    babel({ babelHelpers: 'bundled' })
  ]
}

Основные параметры:

Параметр Назначение
input точка входа
output форматы сборки
plugins плагины обработки

Форматы итоговой сборки

После сборки в каталоге dist/ появляются различные версии библиотеки.

UMD

interact.js

Используется напрямую в браузере:

<script src="interact.js"></script>

Минифицированная версия

interact.min.js

Содержит:

  • сжатый код
  • удалённые комментарии
  • минимальные имена переменных

ESM

interact.esm.js

Используется современными сборщиками:

import interact from 'interactjs'

CommonJS

Используется Node.js и некоторыми сборщиками.

Скрипты сборки

В package.json определены команды сборки.

Пример:

{
  "scripts": {
    "build": "rollup -c",
    "dev": "rollup -c -w",
    "lint": "eslint packages/",
    "test": "npm run lint"
  }
}

Основные команды:

Команда Назначение
build полная сборка
dev сборка в режиме наблюдения
lint проверка кода
test запуск тестов

Запуск сборки:

npm run build

Режим разработки

Во время разработки используется watch mode.

Запуск:

npm run dev

Rollup начинает отслеживать изменения файлов:

packages/**/*.ts

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

  1. компиляция TypeScript
  2. трансформация Babel
  3. генерация сборки

Карты исходников (Source Maps)

Для удобства отладки генерируются source maps.

Файлы:

interact.js.map

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

Пример подключения:

//# sourceMappingURL=interact.js.map

В инструментах разработчика браузера отображается исходный TypeScript.

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

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

Типичная последовательность:

1. сборка
2. запуск тестов
3. проверка линтинга
4. проверка типов

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

npm run build
npm run test

Локальное подключение собранной версии

После сборки библиотеку можно подключить локально.

Структура:

dist/
    interact.js
    interact.min.js

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

<script src="./dist/interact.js"></script>

Пример Jav * aScript:

interact('.item')
  .draggable({
    listeners: {
      move(event) {
        const target = event.target
        const x = (parseFloat(target.getAttribute('data-x')) || 0) + event.dx
        const y = (parseFloat(target.getAttribute('data-y')) || 0) + event.dy

        target.style.transform = `translate(${x}px, ${y}px)`

        target.setAttribute('data-x', x)
        target.setAttribute('data-y', y)
      }
    }
  })

Публикация пакета

После успешной сборки библиотека публикуется в npm.

Основные шаги:

  1. обновление версии
npm version patch

или

minor
major
  1. сборка
npm run build
  1. публикация
npm publish

В пакет включаются:

dist/
types/
package.json
README.md

Оптимизация сборки

Для уменьшения размера итогового файла используются несколько стратегий.

Tree Shaking

Rollup удаляет неиспользуемые модули.

Работает только с ESM.

Пример:

import interact from '@interactjs/interact'

Если не используется gesture, соответствующий код не попадёт в сборку.

Минификация

Плагин:

rollup-plugin-terser

Удаляет:

  • пробелы
  • комментарии
  • длинные имена переменных

Пример:

Исходный код:

function calculatePosition(x, y) {
  return x + y
}

Минифицированный:

function a(b,c){return b+c}

Удаление dev-кода

В production-сборке удаляются:

  • проверки разработки
  • debug-логирование
  • предупреждения

Это уменьшает размер библиотеки.

Генерация TypeScript-типов

Interact.js предоставляет файлы типов для TypeScript.

После компиляции создаются:

dist/index.d.ts

Пример типа:

interface Interactable {
  draggable(options?: DraggableOptions): Interactable
  resizable(options?: ResizableOptions): Interactable
}

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

  • автодополнение
  • проверка типов
  • безопасное использование API

Структура финального пакета

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

interactjs/
    dist/
        interact.js
        interact.min.js
        interact.esm.js
    types/
        index.d.ts
    package.json
    README.md

Каждый формат предназначен для своей среды:

Файл Среда
interact.js браузер
interact.min.js production
interact.esm.js современные сборщики
index.d.ts TypeScript

Типичные проблемы при сборке

Ошибки TypeScript

Причины:

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

Решение:

npm run lint

или

tsc --noEmit

Проблемы с Rollup

Возможные причины:

  • неправильные пути импортов
  • циклические зависимости
  • конфликт плагинов

Решение — проверка:

rollup.config.js

Несовместимость модулей

Некоторые библиотеки используют:

CommonJS

Rollup может требовать дополнительный плагин:

@rollup/plugin-commonjs

Пример подключения:

import commonjs from '@rollup/plugin-commonjs'

plugins: [
  commonjs()
]

Модификация исходников

При разработке новых возможностей библиотеки:

  1. создаётся новый модуль
  2. модуль регистрируется как плагин
  3. обновляются типы TypeScript
  4. добавляются тесты
  5. выполняется сборка

Пример регистрации модуля:

export default function myPlugin(interact) {
  interact.actions.myAction = function () {
    // реализация
  }
}

Подключение:

interact.use(myPlugin)

Модуль автоматически становится частью системы взаимодействий.

Проверка итогового размера библиотеки

Размер бандла проверяется инструментами:

rollup-plugin-visualizer

или

webpack-bundle-analyzer

Это позволяет определить:

  • самые тяжёлые модули
  • неиспользуемый код
  • возможности оптимизации.

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

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

Типичный pipeline:

1. install dependencies
2. lint
3. test
4. build
5. publish

Пример GitHub Actions:

steps:
  - uses: actions/checkout@v3
  - run: npm install
  - run: npm run build
  - run: npm test

Автоматизация гарантирует, что каждая версия библиотеки собирается из корректных исходников и проходит все проверки.

Оглавление