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

Библиотека устанавливается как обычная зависимость проекта и распространяется через npm-экосистему.

npm

npm install popmotion

yarn

yarn add popmotion

pnpm

pnpm add popmotion

После установки пакет становится доступен для импорта в модулях ES и CommonJS (в зависимости от сборки проекта).

Подключение в современном модульном окружении

Popmotion ориентирована на использование в модульных JavaScript-сборках. Основной способ подключения — ES Modules.

Импорт отдельных функций

Библиотека не требует подключения целиком. Используются точечные импорты:

import { animate, spring, tween, physics } from "popmotion";

Такой подход позволяет уменьшить итоговый размер бандла за счёт tree-shaking.

Базовое использование в ES Modules

После установки и импорта функции анимации доступны напрямую.

Простейшая анимация значения

import { animate } from "popmotion";

animate({
  from: 0,
  to: 100,
  duration: 1000,
  onUpdate: (value) => {
    console.log(value);
  }
});

Механизм основан на requestAnimationFrame и управлении временной шкалой, что обеспечивает стабильную частоту обновлений.

Подключение в браузере через сборщик

Vite

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

import { spring } from "popmotion";

spring({
  from: 0,
  to: 1,
  stiffness: 100
}).start(v => {
  console.log(v);
});

Webpack

Webpack требует стандартной ES-интеграции. В большинстве конфигураций достаточно указать модульную сборку.

module.exports = {
  mode: "development",
  entry: "./src/index.js",
};

Импорт Popmotion остаётся идентичным:

import { tween } from "popmotion";

Rollup

Rollup эффективно работает с Popmotion благодаря ESM-структуре пакета.

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

export default {
  input: "src/index.js",
  output: {
    file: "dist/bundle.js",
    format: "esm"
  },
  plugins: [resolve()]
};

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

Popmotion может использоваться без сборщика, напрямую в браузере.

ESM через CDN

<script type="module">
  import { animate } from "https://cdn.skypack.dev/popmotion";

  animate({
    from: 0,
    to: 200,
    onUpdate: (v) => {
      document.body.style.transform = `translateX(${v}px)`;
    }
  });
</script>

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

Структура импорта и доступные модули

Popmotion построена как набор независимых функций. Основные категории:

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

Примеры импортов:

import { inertia } from "popmotion";
import { decay } from "popmotion";
import { keyframes } from "popmotion";

Каждая функция работает автономно и не требует глобальной инициализации библиотеки.

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

В средах, где используется CommonJS, возможен импорт через require:

const popmotion = require("popmotion");

popmotion.animate({
  from: 0,
  to: 50,
  onUpdate: console.log
});

При этом в современных версиях сборщиков предпочтение отдаётся ES Modules, так как они позволяют лучше оптимизировать бандл.

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

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

Пример типизированной анимации

import { animate } from "popmotion";

animate<number>({
  from: 0,
  to: 100,
  onUpdate: (value: number) => {
    console.log(value.toFixed(2));
  }
});

Типизация помогает контролировать значения на этапе компиляции и предотвращает ошибки в колбэках.

Конфигурация окружения и совместимость

Поддержка браузеров

Popmotion ориентирована на современные браузеры с поддержкой:

  • requestAnimationFrame
  • ES6 Modules
  • Promises (для некоторых расширений)

В старых окружениях требуется транспиляция через Babel.

Babel-конфигурация

{
  "presets": [
    ["@babel/preset-env", {
      "targets": "> 0.25%, not dead"
    }]
  ]
}

Использование в React-проектах

Popmotion часто применяется для управления анимациями вне React render-цикла.

Пример интеграции

import { useEffect, useRef } from "react";
import { animate } from "popmotion";

function Box() {
  const ref = useRef(null);

  useEffect(() => {
    animate({
      from: 0,
      to: 300,
      onUpdate: (v) => {
        if (ref.current) {
          ref.current.style.transform = `translateX(${v}px)`;
        }
      }
    });
  }, []);

  return <div ref={ref} className="box" />;
}

Popmotion в данном контексте используется как низкоуровневый движок анимаций, не зависящий от React reconciliation.

Подключение в серверных окружениях

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

import { physics } from "popmotion";

const simulation = physics({
  from: 0,
  velocity: 10
});

Однако отсутствие DOM ограничивает применение визуальных эффектов.

Tree-shaking и оптимизация сборки

Popmotion спроектирована модульно, поэтому использование отдельных функций позволяет исключать неиспользуемый код.

Пример:

import { spring } from "popmotion";

В итоговый бандл попадёт только модуль spring и его зависимости, без остальных частей библиотеки.

Это особенно важно в мобильных приложениях и SPA с ограниченным размером пакета.

Частые ошибки при подключении

Импорт всей библиотеки

import * as popmotion from "popmotion";

Такой подход увеличивает размер бандла и снижает эффективность tree-shaking.

Несовместимость сборщика

При старых конфигурациях Webpack может потребоваться указание:

module: {
  rules: [
    {
      test: /\.m?js$/,
      type: "javascript/auto"
    }
  ]
}

Отсутствие ESM поддержки

В окружениях без ES Modules требуется транспиляция или использование CDN-версии.

Архитектурные особенности подключения

Popmotion не требует глобальной инициализации или создания экземпляра. Каждая функция:

  • возвращает контроллер анимации
  • управляется через start/stop интерфейс
  • работает независимо от других анимаций
const controls = animate({
  from: 0,
  to: 100
});

controls.stop();

Такая модель упрощает интеграцию в любые архитектуры приложений.

Оглавление