Подключение в модульных системах

ES Modules (ESM)

Современный формат модульной системы в JavaScript опирается на стандарт ECMAScript Modules, где зависимости импортируются через директиву import.

Основной пакет timeago.js предоставляет экспорт по умолчанию, который используется для создания экземпляров и выполнения форматирования относительного времени.

import timeago from 'timeago.js';

const instance = timeago();
const result = instance.format(Date.now() - 60000);

В среде ESM важным является статический характер импортов: зависимости анализируются на этапе сборки. Это позволяет инструментам сборки выполнять tree-shaking и исключать неиспользуемые части кода.

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

import timeago, { register } from 'timeago.js';

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

CommonJS (CJS)

В экосистеме Node.js долгое время доминировала система CommonJS, где модули подключаются через require.

timeago.js поддерживает совместимость с CommonJS-средой, обеспечивая доступ к функциональности через стандартный экспорт:

const timeago = require('timeago.js');

const instance = timeago();
const result = instance.format(Date.now() - 120000);

При этом в зависимости от конфигурации сборки пакет может возвращать объект, содержащий поле default, что характерно для интеропа между ESM и CJS:

const timeago = require('timeago.js').default;

Такой вариант часто встречается в проектах, где ESM-модули транспилируются в CommonJS.

Интероперабельность ESM и CommonJS

Современные сборщики обеспечивают совместимость между системами модулей. При подключении timeago.js в смешанных проектах важно учитывать форму экспорта.

Основные сценарии:

  • ESM импортирует CommonJS через автоматическое оборачивание default
  • CommonJS получает ESM через объект module.exports.default
  • сборщики (Vite, Webpack, Rollup) нормализуют структуру импортов

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

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

TypeScript использует статическую типизацию поверх модульной системы JavaScript, поэтому подключение timeago.js осуществляется через стандартные импортные конструкции.

import timeago from 'timeago.js';

const instance = timeago();
const formatted: string = instance.format(Date.now() - 5000);

Типы обычно подтягиваются автоматически, если пакет содержит декларации .d.ts. В противном случае применяется внешний пакет типов или собственные описания.

TypeScript также позволяет явно описывать интерфейсы экземпляра:

type TimeagoInstance = ReturnType<typeof timeago>;

const instance: TimeagoInstance = timeago();

Использование в сборщиках (Webpack, Vite, Rollup)

Сборочные системы анализируют граф зависимостей и оптимизируют подключение модулей.

При интеграции timeago.js важными аспектами становятся:

Webpack

  • поддержка ESM и CJS через loaders
  • возможность tree-shaking при использовании ES Modules
  • кэширование модулей в bundle

Vite

  • нативная поддержка ESM
  • мгновенное подключение пакетов без предварительной бандлизации
  • оптимизация зависимостей через pre-bundling

Rollup

  • агрессивный tree-shaking
  • предпочтение ESM-экспорту
  • генерация компактных библиотечных бандлов

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

В некоторых архитектурах используется ленивое подключение модулей через import().

async function loadTimeago() {
  const { default: timeago } = await import('timeago.js');

  const instance = timeago();
  return instance.format(Date.now() - 30000);
}

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

Подключение в Node.js ESM-окружении

При использовании Node.js с включённым режимом "type": "module" подключение timeago.js полностью соответствует стандарту ECMAScript:

import timeago from 'timeago.js';

const instance = timeago();
console.log(instance.format(Date.now() - 10000));

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

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

Модульные системы опираются на поля package.json, определяющие способ экспорта:

  • main — точка входа для CommonJS
  • module — ESM-версия пакета
  • exports — современная унифицированная схема экспорта

timeago.js обычно предоставляет совместимые точки входа, позволяющие сборщикам автоматически выбирать оптимальный формат модуля.

Особенности интерпретации импортов в разных средах

Различные среды выполнения интерпретируют один и тот же импорт по-разному:

  • браузерные сборки используют ESM напрямую
  • Node.js может переключаться между CJS и ESM
  • сборщики нормализуют структуру модулей до единого формата

Это делает подключение timeago.js устойчивым к различным окружениям выполнения без изменения кода.

Оглавление