Требования к окружению

Библиотека timeago.js предназначена для преобразования даты и времени в человекочитаемый относительный формат:

  • just now
  • 1 minute ago
  • 3 hours ago
  • 2 days ago

Библиотека работает в браузере и в среде Node.js, практически не имеет внешних зависимостей и подходит для:

  • новостных лент;
  • комментариев;
  • чатов;
  • социальных сетей;
  • административных панелей;
  • систем логирования;
  • realtime-интерфейсов.

Перед использованием необходимо подготовить окружение и убедиться в наличии базовых компонентов экосистемы JavaScript.

Поддерживаемые среды выполнения

Браузеры

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

  • Google Chrome
  • Mozilla Firefox
  • Microsoft Edge
  • Safari
  • Opera

Для работы необходима поддержка:

  • ES6-модулей или системы сборки;
  • объекта Date;
  • стандартных JavaScript API.

В большинстве современных проектов дополнительная полификация не требуется.

Node.js

Для серверной разработки библиотека может использоваться в среде Node.js.

Минимально рекомендуется:

  • Node.js 14+
  • npm 6+
  • либо pnpm/yarn последних версий

Проверка версии:

node -v
npm -v

Пример результата:

v20.11.0
10.2.4

Способы подключения библиотеки

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

Наиболее распространённый вариант:

npm install timeago.js

После установки пакет попадает в директорию:

node_modules/timeago.js

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

yarn add timeago.js

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

pnpm add timeago.js

Требования к модульной системе

CommonJS

Для старых проектов Node.js используется CommonJS:

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

Такой формат характерен для:

  • старых Express-приложений;
  • legacy-проектов;
  • некоторых backend-систем.

ES Modules

Современный формат импорта:

import * as timeago from 'timeago.js';

или:

import { format } from 'timeago.js';

Поддержка ES Modules требуется в:

  • Vite;
  • Webpack 5;
  • Rollup;
  • современных браузерах;
  • React;
  • Vue;
  • Svelte;
  • Next.js.

Требования для браузерного подключения без сборщика

Библиотека может использоваться напрямую через CDN.

Пример:

<script src="https://unpkg.com/timeago.js/dist/timeago.min.js"></script>

После подключения становится доступен глобальный объект:

timeago

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

const result = timeago.format('2025-01-10');

console.log(result);

Такой подход подходит для:

  • простых HTML-страниц;
  • прототипов;
  • тестовых проектов;
  • учебных примеров.

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

Поддержка типизации

Библиотека содержит встроенные TypeScript-типизации.

Дополнительные пакеты устанавливать не требуется:

npm install timeago.js

TypeScript автоматически определяет типы.

Требования к TypeScript

Рекомендуется:

  • TypeScript 4+
  • модульная система ESNext
  • moduleResolution: node

Пример конфигурации tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true
  }
}

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

Требования

Для React-проектов достаточно:

  • React 17+
  • React DOM
  • установленного пакета timeago.js

Установка:

npm install react react-dom timeago.js

Пример:

import { format } from 'timeago.js';

function PostDate() {
  return (
    <span>
      {format('2025-05-01')}
    </span>
  );
}

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

Vue 3

Библиотека полностью совместима с Vue 3.

Пример:

import { format } from 'timeago.js';

export default {
  setup() {
    const value = format(Date.now() - 1000 * 60);

    return {
      value
    };
  }
};

Использование в Next.js

Серверный и клиентский рендеринг

В Next.js библиотека может использоваться:

  • на клиенте;
  • на сервере;
  • во время SSR;
  • внутри API routes.

Установка:

npm install timeago.js

Пример:

import { format } from 'timeago.js';

export default function Page() {
  return (
    <div>
      {format(new Date())}
    </div>
  );
}

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

Совместимость

Vite полностью поддерживает библиотеку без дополнительной настройки.

Создание проекта:

npm create vite@latest

Установка библиотеки:

npm install timeago.js

Пример:

import { format } from 'timeago.js';

console.log(format(Date.now() - 60000));

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

Поддержка tree shaking

Библиотека корректно работает с:

  • Webpack;
  • Rollup;
  • Parcel;
  • esbuild.

Современные сборщики умеют удалять неиспользуемый код.

Пример импорта:

import { format } from 'timeago.js';

Такой подход уменьшает итоговый размер bundle.

Требования к объектам даты

Библиотека принимает:

  • строки;
  • timestamp;
  • объекты Date.

Строка даты

format('2025-05-20 10:00:00');

Timestamp

format(1716200000000);

Объект Date

format(new Date());

Корректность формата даты

Некорректные значения приводят к ошибкам форматирования.

Допустимые варианты:

format('2025-05-10');
format('2025-05-10T10:30:00');
format(new Date());

Нежелательные варианты:

format('abc');
format(undefined);
format(null);

Поддержка локализации

Встроенные языки

Библиотека поддерживает большое количество локалей:

  • английский;
  • русский;
  • немецкий;
  • французский;
  • китайский;
  • японский;
  • испанский;
  • украинский;
  • казахский;
  • десятки других.

Подключение локали

Пример русского языка:

import { format, register } from 'timeago.js';
import ru from 'timeago.js/lib/lang/ru';

register('ru', ru);

console.log(format(Date.now() - 1000, 'ru'));

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

Библиотека вычисляет разницу между:

  • текущим временем системы;
  • переданной датой.

Некорректное системное время приводит к неправильным результатам:

5 minutes ago
2 years ago
just now

При серверном рендеринге особенно важно:

  • корректное время ОС;
  • синхронизация через NTP;
  • единый timezone.

Работа с часовыми поясами

Особенности

Сама библиотека не занимается сложной обработкой timezone.

Она использует:

new Date()

Поэтому рекомендуется:

  • хранить даты в UTC;
  • передавать ISO-строки;
  • нормализовывать время на сервере.

Рекомендуемый формат

2025-05-26T12:00:00Z

Такой формат:

  • стандартизирован;
  • одинаково интерпретируется браузерами;
  • безопасен для API;
  • корректно работает в SSR.

Размер библиотеки и производительность

Вес пакета

timeago.js относится к лёгким библиотекам.

Преимущества:

  • маленький размер;
  • высокая скорость работы;
  • отсутствие тяжёлых зависимостей;
  • быстрая инициализация.

Это особенно важно для:

  • мобильных приложений;
  • SPA;
  • высоконагруженных интерфейсов;
  • realtime-обновлений.

Требования к автоматическому обновлению времени

Если интерфейс должен обновлять подписи автоматически:

1 minute ago → 2 minutes ago

необходимо:

  • наличие DOM;
  • таймеров setInterval;
  • активного браузерного окружения.

Пример:

import { render } from 'timeago.js';

render(document.querySelectorAll('.time'));

Работа в серверной среде

SSR и backend

На сервере библиотека работает без DOM.

Поддерживаются:

  • Express;
  • Fastify;
  • NestJS;
  • Koa;
  • Next.js SSR.

Пример:

import { format } from 'timeago.js';

const value = format(Date.now() - 1000 * 60);

console.log(value);

Требования безопасности

Библиотека не выполняет:

  • сетевые запросы;
  • eval;
  • выполнение стороннего кода;
  • работу с файловой системой.

Поэтому она считается безопасной для:

  • браузеров;
  • серверов;
  • SSR;
  • frontend-приложений.

Проверка корректности установки

Тестовый пример

После установки рекомендуется выполнить проверку:

import { format } from 'timeago.js';

console.log(
  format(Date.now() - 1000 * 60 * 5)
);

Ожидаемый результат:

5 minutes ago

Типичные проблемы окружения

Ошибка импорта

Ошибка:

Cannot find module 'timeago.js'

Причины:

  • пакет не установлен;
  • повреждён node_modules;
  • неверный путь импорта.

Решение:

npm install timeago.js

Конфликт CommonJS и ES Modules

Ошибка:

SyntaxError: Cannot use import statement outside a module

Причина:

  • несовместимость модульной системы проекта.

Решения:

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

или настройка:

{
  "type": "module"
}

Ошибка локали

Ошибка:

Cannot find module 'timeago.js/lib/lang/ru'

Причины:

  • неправильный путь;
  • устаревшая версия библиотеки;
  • конфликт сборщика.

Следует проверить:

npm update

Проверка совместимости окружения

Минимальный рекомендуемый стек:

Компонент Рекомендуемая версия
Node.js 14+
npm 6+
TypeScript 4+
React 17+
Vue 3+
Next.js 13+
Vite 4+

Практические рекомендации

Для frontend-проектов

Рекомендуется:

  • использовать ES Modules;
  • подключать библиотеку через npm;
  • хранить даты в UTC;
  • использовать ISO-формат.

Для backend-проектов

Важно:

  • синхронизировать системное время;
  • избегать локальных timezone;
  • форматировать даты на уровне API.

Для SSR-приложений

Следует учитывать:

  • различие времени сервера и клиента;
  • timezone браузера;
  • возможный hydration mismatch.

Рекомендуемый подход:

2025-05-26T12:00:00Z

Проверка готовности окружения

Полностью подготовленное окружение должно обеспечивать:

  • установленный пакет timeago.js;
  • поддержку ES6;
  • корректную работу Date;
  • современный браузер или Node.js;
  • корректную timezone-конфигурацию;
  • поддержку модульной системы проекта;
  • корректную обработку локалей;
  • наличие сборщика для крупных приложений.
Оглавление