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

Корректность установки Lottie Web начинается с подтверждения того, что модуль действительно доступен в окружении исполнения. В зависимости от способа подключения различают несколько сценариев: через пакетный менеджер, через CDN или через сборщик модулей.

При установке через npm пакет должен присутствовать в node_modules:

npm install lottie-web

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

import lottie from "lottie-web";

Отсутствие ошибок на этапе сборки уже является первичным индикатором корректной установки. В случае CommonJS:

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

Ошибки вида Cannot find module 'lottie-web' указывают либо на отсутствие зависимости, либо на повреждённый node_modules.

Проверка наличия глобального объекта при CDN-подключении

При использовании CDN библиотека должна создавать глобальный объект lottie:

<script src="https://cdnjs.cloudflare.com/ajax/libs/lottie-web/5.12.2/lottie.min.js"></script>

После загрузки скрипта в консоли браузера доступна проверка:

console.log(window.lottie);

Корректная установка подтверждается наличием объекта с методами loadAnimation, setQuality, destroy и другими API-функциями. Отсутствие window.lottie означает одну из типичных проблем:

  • скрипт не загрузился из-за 404
  • блокировка CDN
  • неверный порядок подключения скриптов
  • ошибка кеширования

Контроль версии библиотеки

Версия Lottie Web напрямую влияет на поведение API и совместимость с JSON-анимациями. Проверка версии после установки:

import lottie from "lottie-web";

console.log(lottie.version);

При CDN-версии:

console.log(window.lottie?.version);

Несовпадение ожидаемой версии часто приводит к неочевидным ошибкам воспроизведения анимации, особенно при использовании старых JSON-файлов, экспортированных из Adobe After Effects через Bodymovin.

Тестовая инициализация анимации как основной критерий корректности

Фактическая проверка установки считается завершённой только после успешного запуска тестовой анимации.

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

import lottie from "lottie-web";

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

Ключевые признаки корректной установки:

  • отсутствие ошибок в консоли
  • появление SVG-элементов внутри контейнера
  • запуск анимации без ручного триггера
  • отсутствие пустого DOM-узла

Если контейнер остаётся пустым, проверяется цепочка инициализации.

Проверка DOM-контейнера

Одна из частых причин некорректной работы — неверно переданный DOM-элемент.

Корректный контейнер должен существовать в момент вызова:

<div id="app"></div>
document.addEventListener("DOMContentLoaded", () => {
  lottie.loadAnimation({
    container: document.getElementById("app"),
    renderer: "svg",
    loop: true,
    autoplay: true,
    path: "/animation.json"
  });
});

Если контейнер равен null, библиотека не выбрасывает всегда явную ошибку, что приводит к «тихому» отказу рендера.

Проверка загрузки JSON-анимации

Корректность установки библиотеки часто маскируется проблемами загрузки самой анимации.

В DevTools необходимо проверить вкладку Network:

  • запрос animation.json должен иметь статус 200
  • MIME-type должен быть application/json или text/plain
  • размер файла не должен быть нулевым

Типичные ошибки:

  • 404 (неверный путь)
  • CORS блокировка при загрузке с другого домена
  • HTML-ответ вместо JSON (часто из-за fallback роутинга)

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

path: "http://localhost:3000/animation.json"

Проверка работы методов API

Корректная установка подтверждается доступностью основных методов:

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

console.log(typeof anim.play);
console.log(typeof anim.pause);
console.log(typeof anim.destroy);

Ожидаемый результат — function для всех ключевых методов.

Если возвращается undefined, проблема связана с импортом или конфликтом сборки.

Диагностика в окружении сборщиков (Vite, Webpack)

При использовании сборщиков важно учитывать особенности ESM/CJS интероперабельности.

Типичная ошибка:

lottie.loadAnimation is not a function

Причина — неправильный импорт:

import * as lottie from "lottie-web";

или

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

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

console.log(lottie.loadAnimation);

Если функция существует — установка корректна.

Проверка tree-shaking и побочных эффектов сборки

Некоторые конфигурации сборщиков могут ошибочно удалять побочные эффекты библиотеки.

Признак:

  • модуль импортируется без ошибок
  • но window.lottie или loadAnimation отсутствует

Решение диагностируется через временный side-effect импорт:

import "lottie-web";

Если после этого появляется глобальный объект, проблема связана с оптимизацией сборки.

Проверка работы в SSR-средах

В средах серверного рендеринга (например, Next.js) Lottie Web должен инициализироваться только на клиенте.

Ошибка установки часто проявляется как:

  • document is not defined
  • отсутствие контейнера DOM

Корректная проверка:

if (typeof window !== "undefined") {
  const lottie = require("lottie-web");

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

Отсутствие ошибок на сервере и корректный рендер на клиенте подтверждают правильность интеграции.

Проверка конфигурации renderer

Lottie Web поддерживает несколько режимов рендеринга:

  • svg
  • canvas
  • html

Некорректная установка иногда проявляется через падение рендера только в одном режиме.

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

lottie.loadAnimation({
  container: document.getElementById("app"),
  renderer: "canvas",
  loop: true,
  autoplay: true,
  path: "/animation.json"
});

Если один renderer работает, а другой нет, установка библиотеки корректна, а проблема локализуется в окружении или ограничениях DOM.

Отладочные признаки корректной установки

Стабильная работа Lottie Web характеризуется набором наблюдаемых признаков:

  • отсутствие ошибок TypeError и ReferenceError
  • доступность loadAnimation после импорта
  • создание DOM-структуры внутри контейнера
  • наличие <svg> или <canvas> элементов
  • реакция на методы play, pause, stop
  • стабильная загрузка JSON без повторных запросов

Любое отклонение указывает не на анимацию, а на уровень интеграции библиотеки.

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

Некоторые UI-фреймворки могут перехватывать DOM или изменять жизненный цикл элементов.

Типичные симптомы:

  • анимация создаётся и сразу исчезает
  • контейнер очищается повторным рендером
  • события lifecycle удаляют SVG

Диагностика выполняется через закрепление контейнера:

const container = document.getElementById("app");

setTimeout(() => {
  lottie.loadAnimation({
    container,
    renderer: "svg",
    loop: true,
    autoplay: true,
    path: "/animation.json"
  });
}, 0);

Стабильный запуск после рендера подтверждает корректность установки библиотеки и исключает ошибки интеграции.

Проверка корректности событий загрузки

Lottie Web предоставляет события, позволяющие убедиться в корректной работе:

anim.addEventListener("DOMLoaded", () => {
  console.log("loaded");
});

Если событие не вызывается, проблема находится на уровне загрузки JSON или рендера, а не установки библиотеки.

Аналогично проверяются:

  • enterFrame
  • complete
  • loopComplete

Их корректная работа подтверждает полную функциональность установленного пакета.

Оглавление