Структура пакета и точки входа

Библиотека Web Vitals предоставляет набор инструментов для измерения ключевых показателей производительности веб-страниц, таких как LCP, FID, CLS и других. Для эффективного использования библиотеки необходимо понимать её структуру и точки входа, которые позволяют интегрировать метрики в проекты на JavaScript.

Основная структура пакета

Пакет web-vitals распространяется через npm и включает следующие элементы:

  • index.js – основной файл, который служит точкой входа для всех функций библиотеки. Экспортируются функции для измерения конкретных метрик.
  • lib/ – каталог с внутренними модулями библиотеки. В нём находятся реализации отдельных измерений и вспомогательные функции для обработки событий.
  • dist/ – сборки для браузера, включающие минифицированные и неминифицированные версии, предназначенные для прямого подключения через <script> или bundler.
  • package.json – содержит информацию о зависимостях, версиях и точках входа для Node.js и браузера.
  • README.md и документация – объясняет API и способы интеграции.

Каждый из этих элементов выполняет конкретную функцию. index.js предоставляет единую точку доступа, в то время как внутренние модули в lib/ инкапсулируют сложную логику обработки метрик, минимизируя риск конфликтов и упрощая поддержку.

Экспортируемые функции

В точке входа index.js доступны следующие функции:

  • getCLS(callback, reportAllChanges) – измеряет Cumulative Layout Shift, накапливая смещения элементов страницы. Параметры:

    • callback – функция, которая получает объект метрики.
    • reportAllChanges (необязательный) – если true, вызывается при каждом смещении.

  • getFID(callback) – измеряет First Input Delay, фиксируя задержку между первым взаимодействием пользователя и реакцией страницы.

  • getLCP(callback) – измеряет Largest Contentful Paint, определяя момент рендеринга наибольшего видимого элемента.

  • getTTFB(callback) – измеряет Time to First Byte, позволяя оценить скорость отклика сервера.

Каждая функция создаёт наблюдателя за соответствующими событиями браузера и возвращает объект метрики с ключевыми свойствами: value, entries, id.

Работа с точками входа

Точка входа библиотеки позволяет подключать метрики разными способами:

1. Через ESM-модули:

import { getCLS, getFID, getLCP } from 'web-vitals';

getCLS(console.log);
getFID(console.log);
getLCP(console.log);

2. Через CommonJS:

const { getCLS, getFID, getLCP } = require('web-vitals');

getCLS(console.log);
getFID(console.log);
getLCP(console.log);

3. Через глобальный объект в браузере:

<script src="https://unpkg.com/web-vitals/dist/web-vitals.iife.js"></script>
<script>
  webVitals.getCLS(console.log);
  webVitals.getFID(console.log);
</script>

Это позволяет интегрировать библиотеку как в современные сборщики (Webpack, Vite), так и напрямую в HTML без сборки.

Взаимодействие модулей внутри пакета

Внутренние модули lib/ разделены по типу метрики. Основные компоненты:

  • metrics/ – реализует конкретные вычисления метрик, используя PerformanceObserver и другие API браузера.
  • utils/ – содержит функции для генерации уникальных идентификаторов, нормализации значений и фильтрации событий.
  • report/ – отвечает за форматирование и передачу результатов в callback, обеспечивая совместимость с различными средами (браузер, Node.js).

Каждый модуль изолирован, что позволяет обновлять внутреннюю логику без изменения внешнего API.

Особенности точек входа

  • Минимизация размера пакета: Точка входа экспортирует только основные функции, остальные модули остаются скрытыми.
  • Совместимость с разными окружениями: Поддерживаются ESM, CommonJS и IIFE-сборка для браузеров.
  • Поддержка TypeScript: В пакете присутствуют декларации типов (.d.ts), что облегчает автодополнение и проверку типов при использовании в TypeScript-проектах.

Рекомендации по использованию

  • Подключать только те функции, которые реально используются, чтобы минимизировать размер бандла.
  • Вызывать функции после загрузки DOM, чтобы метрики корректно фиксировали состояние элементов.
  • Для продакшн-сборок использовать минифицированные версии из dist/, чтобы снизить нагрузку на сеть.

Структура пакета и точки входа в Web Vitals обеспечивают лёгкость интеграции, модульность и гибкость в работе с метриками производительности, что позволяет строить комплексный мониторинг без усложнения архитектуры приложения.

Оглавление