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

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

Для установки библиотеки требуется установленный пакетный менеджер npm, входящий в состав Node.js. Проверка доступности выполняется командами:

node -v
npm -v

При отсутствии Node.js необходимо выполнить установку с официального сайта или через менеджеры пакетов системы.

Инициализация проекта

Перед установкой зависимостей создаётся файл package.json, содержащий метаданные проекта и список зависимостей. В новом каталоге проекта выполняется:

npm init -y

Флаг -y автоматически заполняет файл значениями по умолчанию.

Структура проекта после инициализации:

project/
├── package.json

Установка Headroom.js

Библиотека устанавливается из npm-реестра:

npm install headroom.js

После установки в package.json добавляется запись:

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

Также создаётся директория node_modules, содержащая исходный код библиотеки и её зависимости.

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

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

  1. Проверка наличия в node_modules:
node_modules/headroom.js/
  1. Использование команды:
npm list headroom.js

Ожидаемый вывод:

project@1.0.0
└── headroom.js@0.12.0

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

Использование с ES-модулями

В средах с поддержкой ES Modules (например, при использовании сборщиков):

import Headroom from "headroom.js";

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

Для Node.js или старых конфигураций:

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

Интеграция с HTML

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

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

Важно, чтобы скрипт выполнялся после загрузки DOM:

document.addEventListener("DOMContentLoaded", () => {
  const header = document.querySelector("header");
  const headroom = new Headroom(header);
  headroom.init();
});

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

Webpack

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

import Headroom from "headroom.js";

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

Vite

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

import Headroom from "headroom.js";

Запуск:

npm run dev

Rollup

При необходимости подключается плагин для работы с node-модулями:

npm install @rollup/plugin-node-resolve

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

import resolve from "@rollup/plugin-node-resolve";

export default {
  plugins: [resolve()]
};

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

Если библиотека используется исключительно на этапе разработки (редкий случай), установка выполняется с флагом:

npm install headroom.js --save-dev

В package.json:

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

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

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

npm uninstall headroom.js

Запись автоматически удаляется из package.json.

Версионирование

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

npm install headroom.js@0.11.0

Использование точной версии без диапазонов:

npm install headroom.js@0.12.0 --save-exact

В package.json:

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

Работа с lock-файлом

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

Удалять его без необходимости не рекомендуется.

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

Очистка кэша npm:

npm cache clean --force

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

rm -rf node_modules package-lock.json
npm install

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

При необходимости можно отказаться от npm и подключить библиотеку через CDN:

<script src="https://unpkg.com/headroom.js"></script>

Однако при использовании npm достигаются преимущества:

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

Типовые проблемы

Ошибка: module not found

Причины:

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

Решение:

npm install

Несовместимость версий

Решение:

  • обновление npm:
npm install -g npm
  • установка конкретной версии библиотеки

Конфликты зависимостей

Решение:

npm install --legacy-peer-deps

Минимальный рабочий пример

Структура:

project/
├── index.html
├── main.js
├── package.json

main.js:

import Headroom from "headroom.js";

document.addEventListener("DOMContentLoaded", () => {
  const header = document.querySelector("header");
  const headroom = new Headroom(header);
  headroom.init();
});

index.html:

<!DOCTYPE html>
<html lang="ru">
<head>
  <meta charset="UTF-8">
  <title>Headroom</title>
</head>
<body>
  <header>Header</header>
  <script type="module" src="./main.js"></script>
</body>
</html>

После установки и запуска сборщика библиотека готова к использованию в проекте.

Оглавление