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

Библиотека lottie-web распространяется через npm и устанавливается как стандартный пакет JavaScript-экосистемы. В современных проектах она подключается как зависимость для сборщиков вроде Vite, Webpack, Rollup или Parcel.

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

npm install lottie-web

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

{
  "dependencies": {
    "lottie-web": "^5.x.x"
  }
}

lottie-web поставляется в виде готового JavaScript-модуля без необходимости дополнительной сборки. Это позволяет использовать библиотеку сразу после установки.

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

В проектах, использующих Yarn как менеджер пакетов, подключение выполняется аналогичным образом:

yarn add lottie-web

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

{
  "dependencies": {
    "lottie-web": "^5.x.x"
  }
}

Yarn автоматически загружает пакет и размещает его в node_modules, сохраняя lock-файл (yarn.lock) для детерминированной установки в разных окружениях.

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

Современные сборщики поддерживают ES Modules-импорт, который является основным способом использования lottie-web в приложениях.

Базовый импорт:

import lottie from "lottie-web";

После импорта становится доступен основной API библиотеки, включая методы управления анимациями, загрузки JSON и привязки к DOM-элементам.

Пример инициализации:

import lottie from "lottie-web";

const animation = lottie.loadAnimation({
  container: document.getElementById("animation"),
  renderer: "svg",
  loop: true,
  autoplay: true,
  path: "/animations/example.json"
});

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

В средах, где используется CommonJS (например, Node.js-проекты без ESM), применяется require:

const lottie = require("lottie-web");

Дальнейшее использование API не отличается от ES Modules-версии, поскольку экспорт библиотеки совместим с обеими системами модулей.

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

Vite

В проектах на Vite библиотека подключается без дополнительной конфигурации:

import lottie from "lottie-web";

Vite обрабатывает зависимости через ESM, поэтому lottie-web интегрируется напрямую.

Webpack

В Webpack использование аналогичное, однако при необходимости может потребоваться настройка для обработки JSON-анимаций:

import lottie from "lottie-web";

Загрузка JSON-файлов анимаций обеспечивается через file-loader или встроенные asset modules:

module.exports = {
  module: {
    rules: [
      {
        test: /\.json$/,
        type: "asset/resource"
      }
    ]
  }
};

Rollup

В Rollup подключение также выполняется через стандартный импорт ES Modules:

import lottie from "lottie-web";

При необходимости применяется плагин @rollup/plugin-node-resolve для корректного разрешения зависимостей из node_modules.

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

Библиотека lottie-web включает собственные типы, однако в некоторых окружениях требуется установка дополнительных деклараций:

npm install --save-dev @types/lottie-web

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

import lottie, { AnimationItem } from "lottie-web";

const animation: AnimationItem = lottie.loadAnimation({
  container: document.getElementById("animation") as Element,
  renderer: "svg",
  loop: true,
  autoplay: true,
  path: "/animations/example.json"
});

Тип AnimationItem описывает экземпляр анимации и предоставляет доступ к методам управления воспроизведением, остановкой и обновлением состояния.

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

После установки в node_modules/lottie-web содержится несколько ключевых компонентов:

  • основной entry-point (build/player/lottie.js или аналогичный)
  • ESM/CJS сборки
  • вспомогательные утилиты для рендереров SVG, Canvas и HTML
  • JSON-парсер анимаций
  • типы (в зависимости от версии)

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

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

Браузер через сборщик

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

import lottie from "lottie-web";

Node.js (ограниченное использование)

Библиотека не предназначена для полноценного серверного рендеринга, однако может использоваться в SSR-окружениях для подготовки конфигураций анимации без DOM.

const lottie = require("lottie-web");

Работа с JSON-анимациями после установки

После установки пакет не включает анимации по умолчанию. JSON-файлы создаются в инструментах вроде Adobe After Effects с плагином Bodymovin и затем подключаются через path или animationData.

Пример загрузки локального JSON:

import lottie from "lottie-web";
import animationData from "./animation.json";

lottie.loadAnimation({
  container: document.querySelector("#animation"),
  renderer: "svg",
  loop: true,
  autoplay: true,
  animationData
});

При таком подходе JSON включается в бандл сборщиком.

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

В некоторых конфигурациях возникают ошибки, связанные с резолвингом модулей:

  • отсутствие поддержки ESM в старых сборщиках
  • конфликт типов TypeScript
  • неправильная обработка JSON-файлов
  • дублирование экземпляров библиотеки при микрофронтендах

Корректная установка через npm или yarn с использованием актуальных версий сборщиков устраняет большинство подобных проблем.

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

lottie-web поддерживает современные браузеры с ES5+ окружением. При использовании через npm/yarn важно учитывать версию пакета:

  • версии 5.x — стабильная основная линия
  • более ранние версии — устаревшие API и отличия в структуре экспорта

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

npm update lottie-web

или

yarn upgrade lottie-web
Оглавление