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

Использование менеджера пакетов npm является стандартным способом подключения библиотеки Locomotive Scroll в современных JavaScript-проектах. Такой подход обеспечивает удобное управление зависимостями, контроль версий и интеграцию с системами сборки.

Подготовка проекта

Перед установкой необходимо убедиться, что в проекте инициализирован файл package.json. Если он отсутствует, выполняется команда:

npm init -y

В результате создаётся базовая конфигурация проекта, в которой будут фиксироваться все зависимости, включая Locomotive Scroll.

Установка пакета

Установка библиотеки выполняется через npm:

npm install locomotive-scroll

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

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

После установки библиотека содержит несколько ключевых файлов:

  • dist/locomotive-scroll.js — основной JavaScript-файл
  • dist/locomotive-scroll.min.js — минифицированная версия
  • dist/locomotive-scroll.css — стили, необходимые для корректной работы
  • дополнительные ресурсы (например, шрифты или вспомогательные файлы)

Использование CSS-файла обязательно, так как он отвечает за базовую логику отображения и анимации прокрутки.

Подключение в проекте

Импорт в JavaScript

В среде с поддержкой модулей (например, при использовании сборщиков вроде Webpack, Vite или Parcel) библиотека подключается следующим образом:

import LocomotiveScroll from 'locomotive-scroll';
import 'locomotive-scroll/dist/locomotive-scroll.css';

После импорта доступен конструктор для создания экземпляра скролла.

Инициализация

const scroll = new LocomotiveScroll({
  el: document.querySelector('[data-scroll-container]'),
  smooth: true
});

Ключевые параметры:

  • el — контейнер, внутри которого будет работать кастомный скролл
  • smooth — включает плавную прокрутку

Подключение через CommonJS

В проектах, использующих CommonJS (например, старые конфигурации Node.js или Webpack), применяется следующий синтаксис:

const LocomotiveScroll = require('locomotive-scroll').default;
require('locomotive-scroll/dist/locomotive-scroll.css');

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

Webpack

Для корректной работы CSS требуется соответствующий загрузчик:

npm install style-loader css-loader --save-dev

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

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader']
      }
    ]
  }
};

Vite

Vite поддерживает импорт CSS «из коробки», поэтому дополнительная настройка не требуется:

import 'locomotive-scroll/dist/locomotive-scroll.css';

Parcel

Parcel автоматически обрабатывает CSS, дополнительных действий не требуется.

Работа с типами (TypeScript)

Locomotive Scroll не всегда поставляется с встроенными типами. При необходимости можно:

  1. Проверить наличие типов:
npm install @types/locomotive-scroll
  1. При отсутствии — описать типы вручную:
declare module 'locomotive-scroll';

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

После подключения и инициализации необходимо убедиться, что:

  • контейнер имеет атрибут data-scroll-container
  • элементы, участвующие в анимации, используют data-scroll
  • страница корректно реагирует на прокрутку

Пример HTML-разметки:

<div data-scroll-container>
  <section data-scroll-section>
    <h1 data-scroll data-scroll-speed="2">Заголовок</h1>
  </section>
</div>

Частые проблемы при установке

Отсутствие стилей

Если не подключён CSS-файл, прокрутка будет работать некорректно или не будет работать вовсе.

Неправильный контейнер

Библиотека требует строгой структуры DOM. Контейнер должен быть один и оборачивать весь контент.

Конфликт со сторонними библиотеками

Некоторые библиотеки, влияющие на скролл (например, анимационные фреймворки), могут конфликтовать с Locomotive Scroll.

SSR (Server-Side Rendering)

В средах вроде Next.js необходимо инициализировать библиотеку только на клиенте:

import { useEffect } from 'react';

useEffect(() => {
  const scroll = new LocomotiveScroll({
    el: document.querySelector('[data-scroll-container]'),
    smooth: true
  });
}, []);

Обновление библиотеки

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

npm update locomotive-scroll

При необходимости установки конкретной версии:

npm install locomotive-scroll@4.1.4

Контроль версии особенно важен при использовании нестабильных или экспериментальных функций.

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

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

npm uninstall locomotive-scroll

Это удалит библиотеку из node_modules и из списка зависимостей проекта.

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

  • использовать lock-файлы (package-lock.json) для фиксации версий
  • подключать только необходимые ресурсы
  • следить за обновлениями библиотеки и изменениями API
  • тестировать работу скролла после каждого обновления зависимостей
Оглавление