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

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

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

Установка выполняется одной командой:

yarn add headroom.js

После выполнения:

  • библиотека будет добавлена в директорию node_modules
  • в package.json автоматически появится запись в разделе dependencies
  • будет зафиксирована версия пакета для воспроизводимых сборок

Пример фрагмента package.json:

{
  "dependencies": {
    "headroom.js": "^0.12.0"
  }
}

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

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

yarn list --pattern headroom.js

Это позволяет убедиться, что используется ожидаемая версия, особенно в проектах с большим количеством зависимостей.

Импорт в проекте

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

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

import Headroom from "headroom.js";

CommonJS (например, в Node.js или старых сборках):

const Headroom = require("headroom.js");

Использование с бандлерами

При использовании инструментов сборки (например, Webpack, Vite, Rollup):

  • никаких дополнительных настроек для подключения не требуется
  • библиотека автоматически включается в итоговый бандл
  • tree shaking не применяется, так как пакет экспортирует единый класс

Подключение стилей

Headroom.js не включает CSS, но предполагает использование классов, которые добавляются к элементу. После установки через yarn необходимо самостоятельно определить стили.

Минимальный пример:

.headroom {
  transition: transform 0.3s ease;
}

.headroom--pinned {
  transform: translateY(0%);
}

.headroom--unpinned {
  transform: translateY(-100%);
}

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

Минимальная инициализация для проверки:

import Headroom from "headroom.js";

const header = document.querySelector("header");
const headroom = new Headroom(header);

headroom.init();

Если при прокрутке страницы элемент начинает скрываться и появляться — установка выполнена корректно.

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

Для фиксации определённой версии:

yarn add headroom.js@0.12.0

Это важно для:

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

Установка как devDependency

В редких случаях (например, при использовании только в демонстрационных или тестовых сборках) библиотеку можно установить как dev-зависимость:

yarn add headroom.js --dev

Однако для клиентских приложений библиотека обычно относится к основным зависимостям (dependencies).

Работа в офлайн-режиме

Yarn кэширует пакеты, поэтому после первой установки Headroom.js может устанавливаться без доступа к сети:

yarn install --offline

Это ускоряет CI/CD процессы и локальную разработку.

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

При необходимости удаления:

yarn remove headroom.js

После выполнения:

  • пакет удаляется из node_modules
  • запись удаляется из package.json

Особенности версионирования

Headroom.js придерживается семантического версионирования (SemVer):

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

Использование диапазона версий (^) означает автоматическое получение минорных обновлений:

"headroom.js": "^0.12.0"

Для полной фиксации версии используется точное значение:

"headroom.js": "0.12.0"

Интеграция в монорепозитории

При использовании Yarn Workspaces:

  • Headroom.js устанавливается на уровне workspace или корневого проекта
  • повторная установка в каждом пакете не требуется
  • зависимость переиспользуется благодаря hoisting

Пример:

yarn workspace frontend add headroom.js

Возможные проблемы и решения

1. Модуль не найден

Причина:

  • не выполнена установка
  • повреждён node_modules

Решение:

yarn install

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

rm -rf node_modules yarn.lock
yarn install

2. Конфликт версий

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

yarn why headroom.js

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

3. Проблемы с SSR

Headroom.js использует window, поэтому при серверном рендеринге требуется:

if (typeof window !== "undefined") {
  const Headroom = require("headroom.js");
}

или динамический импорт.

Установка через yarn обеспечивает:

  • управление версиями
  • быструю установку
  • удобную интеграцию с современными инструментами сборки
  • воспроизводимость окружения

Это делает данный способ основным для использования Headroom.js в производственных проектах.

Оглавление