Установка и подключение

Библиотека Motion One распространяется как набор модулей, основной из которых — @motionone/dom, предназначенный для анимации DOM-элементов.

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

npm install @motionone/dom

Через yarn:

yarn add @motionone/dom

Через pnpm:

pnpm add @motionone/dom

После установки пакет становится доступным для импорта в модульной системе ES Modules, а также в сборщиках вроде Vite, Webpack и Rollup.

Импорт и базовое подключение

Основная функция библиотеки — animate. Она импортируется напрямую из пакета:

import { animate } from "@motionone/dom";

После импорта становится доступен API для управления анимациями DOM-элементов без необходимости использования CSS keyframes или сторонних решений.

Простейший пример подключения анимации:

import { animate } from "@motionone/dom";

const box = document.querySelector(".box");

animate(
  box,
  { opacity: 1, transform: "translateY(0px)" },
  { duration: 0.6, easing: "ease-out" }
);

Подключение в проектах с Vite

Vite поддерживает ES Modules из коробки, поэтому интеграция сводится к стандартному импорту.

Структура проекта:

project/
 ├─ index.html
 ├─ main.js
 └─ style.css

Файл main.js:

import { animate } from "@motionone/dom";

animate(".title", { opacity: [0, 1], y: [-20, 0] }, { duration: 0.5 });

Vite автоматически обрабатывает зависимости, поэтому дополнительная настройка не требуется.

Подключение в Webpack-проектах

В Webpack использование идентично, но важно наличие поддержки ES Modules через Babel или встроенные настройки сборки.

Установка:

npm install @motionone/dom

Пример использования:

import { animate } from "@motionone/dom";

animate(".card", { scale: [0.8, 1], opacity: [0, 1] }, { duration: 0.4 });

Если проект использует старую конфигурацию, требуется проверка babel-loader для корректной обработки импортов.

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

Для простых сценариев без сборщика можно подключить библиотеку напрямую через CDN.

<script type="module">
  import { animate } from "https://cdn.jsdelivr.net/npm/@motionone/dom/+esm";

  animate("h1", { opacity: [0, 1], y: [-30, 0] }, { duration: 0.8 });
</script>

Такой способ удобен для прототипов и небольших страниц, где нет необходимости в сборке проекта.

Подключение в браузерном окружении без модулей

В классических сценариях можно использовать глобальные сборки, однако Motion One ориентирован на ESM, поэтому предпочтение отдаётся модульному подключению через type="module".

Пример:

<script type="module">
  import { animate } from "https://cdn.jsdelivr.net/npm/@motionone/dom/+esm";

  animate(".box", { x: 100 }, { duration: 1 });
</script>

Структура пакета и зависимости

Основной пакет @motionone/dom построен поверх ядра Motion One, которое реализует:

  • управление анимационными эффектами
  • интерполяцию значений
  • поддержку easing-функций
  • управление временными линиями

Внутри экосистемы также используются дополнительные пакеты:

  • @motionone/core — базовая логика анимаций
  • @motionone/utils — вспомогательные функции
  • @motionone/svelte — интеграция со Svelte
  • @motionone/react — React-обёртки

При установке @motionone/dom зависимости подтягиваются автоматически.

Подключение в React-проектах

Хотя Motion One не требует специальной интеграции, в React его используют через эффекты жизненного цикла:

import { useEffect, useRef } from "react";
import { animate } from "@motionone/dom";

export default function Component() {
  const ref = useRef(null);

  useEffect(() => {
    animate(ref.current, { opacity: [0, 1], y: [20, 0] }, { duration: 0.5 });
  }, []);

  return <div ref={ref}>Текст</div>;
}

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

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

Типичные признаки корректной интеграции:

  • отсутствие ошибок Cannot resolve module
  • выполнение анимации при вызове animate
  • поддержка селекторов CSS и DOM-элементов

Если анимация не запускается, чаще всего причина связана с:

  • неверным путём импорта
  • отсутствием DOM-элемента на момент вызова
  • конфликтом с SSR (server-side rendering)

Работа в SSR-окружениях

В средах с серверным рендерингом (например, Next.js) доступ к window и DOM отсутствует на сервере.

Поэтому подключение должно происходить только на клиенте:

import { useEffect } from "react";
import { animate } from "@motionone/dom";

useEffect(() => {
  animate(".item", { opacity: [0, 1] });
}, []);

Такой подход предотвращает выполнение анимаций на сервере.

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

Motion One спроектирован как легковесная библиотека:

  • поддерживает tree-shaking
  • импортирует только используемые функции
  • минимизирует runtime-накладные расходы

Пример оптимального импорта:

import { animate } from "@motionone/dom";

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

Подключение в TypeScript-проектах

Библиотека содержит встроенные типы, поэтому дополнительных @types пакетов не требуется.

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

import { animate } from "@motionone/dom";

const el = document.querySelector<HTMLElement>(".box");

if (el) {
  animate(el, { opacity: [0, 1] }, { duration: 0.5 });
}

TypeScript корректно выводит типы параметров и конфигураций анимации.

Оглавление