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

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

npm install vivus

или при использовании Yarn:

yarn add vivus

Пакет устанавливается в node_modules и становится доступным для импорта в модулях сборщика. Библиотека Vivus не требует дополнительных зависимостей и работает как в браузерной среде, так и в современных фронтенд-сборках.

В проектах, использующих ES Modules (Vite, modern Webpack, Rollup, Parcel), библиотека импортируется напрямую:

import Vivus from 'vivus';

const animation = new Vivus('my-svg', {
  type: 'delayed',
  duration: 200,
  start: 'autostart'
});

Импорт возвращает конструктор, который создаёт экземпляр анимации для указанного SVG-элемента.

SVG-элемент должен присутствовать в DOM до инициализации:

<svg id="my-svg" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
  <path d="M10 10 L90 90" />
</svg>

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

В средах Node.js или старых конфигурациях Webpack применяется CommonJS-синтаксис:

const Vivus = require('vivus');

const animation = new Vivus('my-svg', {
  type: 'sync',
  duration: 150
});

При этом важно учитывать, что сама библиотека ориентирована на браузер, поэтому выполнение должно происходить в окружении с DOM (например, после загрузки страницы или в клиентской части SPA).

Подключение в SPA-фреймворках

React

В React инициализация выполняется после монтирования компонента:

import { useEffect } from 'react';
import Vivus from 'vivus';

export default function Logo() {
  useEffect(() => {
    new Vivus('logo-svg', {
      type: 'scenario-sync',
      duration: 180
    });
  }, []);

  return (
    <svg id="logo-svg" viewBox="0 0 200 200">
      <path d="M20 20 L180 180" />
    </svg>
  );
}

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

Vue

В Vue 3 логика аналогична, но размещается в onMounted:

import { onMounted } from 'vue';
import Vivus from 'vivus';

export default {
  setup() {
    onMounted(() => {
      new Vivus('logo-svg', {
        type: 'delayed',
        duration: 220
      });
    });
  }
};

Работа с bundler-средами (Vite, Webpack, Rollup)

При использовании сборщиков важно учитывать, что Vivus работает с DOM напрямую и не предназначена для серверного рендеринга.

Защита от SSR-ошибок

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

if (typeof window !== 'undefined') {
  import('vivus').then(({ default: Vivus }) => {
    new Vivus('logo-svg', { duration: 200 });
  });
}

Динамический импорт

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

async function initAnimation() {
  const { default: Vivus } = await import('vivus');

  new Vivus('logo-svg', {
    type: 'oneByOne',
    duration: 250
  });
}

Подход особенно эффективен для ленивых компонентов интерфейса или анимаций, активируемых при прокрутке.

Типизация и работа с TypeScript

Типы для Vivus не всегда поставляются встроенно, поэтому используется базовая декларация:

declare module 'vivus' {
  export default class Vivus {
    constructor(
      element: string | HTMLElement,
      options?: {
        type?: string;
        duration?: number;
        start?: string;
      }
    );
  }
}

После добавления декларации импорт становится типобезопасным:

import Vivus from 'vivus';

const anim = new Vivus('svg-id', {
  duration: 200,
  type: 'delayed'
});

Особенности работы в модульной архитектуре

При использовании npm-подключения важно учитывать ряд особенностей интеграции:

  • SVG должен быть доступен в DOM до создания экземпляра
  • Инициализация должна выполняться после гидратации интерфейса в SPA
  • Повторное создание экземпляра на одном элементе может приводить к конфликтам анимации
  • Библиотека напрямую манипулирует атрибутами stroke, pathLength и getTotalLength

Подключение нескольких анимаций

В npm-среде возможно создание нескольких независимых экземпляров:

import Vivus from 'vivus';

const logo = new Vivus('logo', { duration: 180 });
const icon = new Vivus('icon', { duration: 120, type: 'sync' });
const line = new Vivus('line', { duration: 90, type: 'oneByOne' });

Каждый экземпляр управляет своим SVG без общего состояния, что позволяет масштабировать анимации на уровне интерфейса.

Контроль жизненного цикла в приложениях

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

  • удаление SVG из DOM
  • обнуление ссылок на экземпляр
  • предотвращение повторной инициализации
let animation = null;

function mount() {
  animation = new Vivus('svg', { duration: 200 });
}

function unmount() {
  document.getElementById('svg')?.remove();
  animation = null;
}

Оптимизация загрузки через npm

В сборках можно уменьшить влияние библиотеки на стартовый пакет:

  • использование динамического импорта
  • разделение чанков
  • lazy-loading SVG-анимаций
  • загрузка только на интерактивных экранах
button.addEventListener('click', async () => {
  const { default: Vivus } = await import('vivus');
  new Vivus('svg', { duration: 150 });
});

Работа с современными сборками

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

import Vivus from 'vivus';

Webpack 5 также корректно обрабатывает пакет благодаря поддержке ES-модулей внутри зависимости.

Использование в компонентной архитектуре

При компонентном подходе анимация привязывается к конкретному жизненному циклу:

  • инициализация при монтировании
  • отсутствие повторного запуска без необходимости
  • контроль уникальности ID SVG

Такая модель позволяет масштабировать использование Vivus в сложных интерфейсах с десятками независимых анимаций.

Оглавление