Подключение и регистрация плагинов

Day.js распространяется как модульная библиотека, поддерживающая CommonJS, ESM и подключение через CDN. В основе лежит функция dayjs(), которая создаёт и возвращает неизменяемые объекты даты. Библиотека спроектирована так, чтобы минимизировать размер бандла за счёт системы плагинов, подключаемых явно.

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

В большинстве современных проектов Day.js устанавливается через менеджер пакетов:

npm install dayjs

или

yarn add dayjs

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

Подключение в CommonJS (Node.js)

В среде Node.js, использующей CommonJS, подключение осуществляется через require:

const dayjs = require('dayjs');

const now = dayjs();
console.log(now.format());

Объект dayjs представляет собой фабричную функцию. Каждый вызов возвращает новый экземпляр даты, не изменяющий исходные данные.

Подключение в ESM (ES Modules)

В современных сборщиках и Node.js с поддержкой ES Modules используется синтаксис import:

import dayjs from 'dayjs';

const date = dayjs('2026-01-01');
console.log(date.format('YYYY-MM-DD'));

ESM-импорт обеспечивает лучшую совместимость с tree-shaking, что особенно важно при использовании плагинов и уменьшении размера итогового бандла.

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

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

<script src="https://unpkg.com/dayjs"></script>
<script>
  const now = dayjs();
  console.log(now.format());
</script>

После подключения библиотека доступна через глобальный объект dayjs.

Архитектура плагинов Day.js

Базовая функциональность Day.js намеренно минимальна. Дополнительные возможности реализуются через плагины, которые подключаются вручную.

Плагин в Day.js — это функция, которая расширяет прототип библиотеки или добавляет новые методы. Подключение плагина выполняется через метод:

dayjs.extend(plugin);

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

Регистрация плагинов в Node.js и ESM

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

import dayjs from 'dayjs';
import utc from 'dayjs/plugin/utc';

dayjs.extend(utc);

const d = dayjs().utc();
console.log(d.format());

В CommonJS аналогичный процесс выглядит следующим образом:

const dayjs = require('dayjs');
const utc = require('dayjs/plugin/utc');

dayjs.extend(utc);

console.log(dayjs().utc().format());

Плагин не активируется автоматически. Даже если он установлен в проекте, его функциональность недоступна без явного вызова extend.

Принцип работы extend

Метод extend модифицирует внутреннюю структуру Day.js, добавляя новые методы или изменяя поведение экземпляров. После регистрации плагина все создаваемые объекты начинают поддерживать расширенный функционал.

Пример с добавлением поддержки временных зон:

import dayjs from 'dayjs';
import timezone from 'dayjs/plugin/timezone';

dayjs.extend(timezone);

const moscow = dayjs().tz('Europe/Moscow');
console.log(moscow.format());

Важно, что extend влияет на глобальный экземпляр Day.js в рамках текущего модуля. Повторное подключение одного и того же плагина не создаёт новых экземпляров, но может привести к непредсказуемому поведению при неправильной организации импортов.

Порядок подключения плагинов

Некоторые плагины зависят друг от друга. В таких случаях порядок регистрации имеет значение. Например, расширения, работающие с UTC и временными зонами, часто требуют предварительного подключения базового функционала:

import dayjs from 'dayjs';
import utc from 'dayjs/plugin/utc';
import timezone from 'dayjs/plugin/timezone';

dayjs.extend(utc);
dayjs.extend(timezone);

Нарушение порядка может привести к отсутствию методов или ошибкам выполнения.

Подключение нескольких плагинов

Day.js поддерживает одновременное использование нескольких расширений. Каждый плагин регистрируется отдельно:

import dayjs from 'dayjs';
import utc from 'dayjs/plugin/utc';
import advancedFormat from 'dayjs/plugin/advancedFormat';
import relativeTime from 'dayjs/plugin/relativeTime';

dayjs.extend(utc);
dayjs.extend(advancedFormat);
dayjs.extend(relativeTime);

console.log(dayjs().fromNow());
console.log(dayjs().format('Do MMMM YYYY'));

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

Использование плагинов через CDN

При подключении через CDN плагины доступны как отдельные глобальные переменные. Каждый плагин добавляется вручную:

<script src="https://unpkg.com/dayjs"></script>
<script src="https://unpkg.com/dayjs/plugin/utc"></script>

<script>
  dayjs.extend(dayjs_plugin_utc);

  console.log(dayjs().utc().format());
</script>

Имена глобальных переменных формируются по шаблону dayjs_plugin_<name>.

Поведение плагинов в рантайме

После вызова extend функциональность становится частью экземпляров, создаваемых через dayjs(). Уже созданные объекты также получают доступ к новым методам, поскольку Day.js использует прототипное расширение.

import dayjs from 'dayjs';
import isLeapYear from 'dayjs/plugin/isLeapYear';

dayjs.extend(isLeapYear);

const date = dayjs('2024-01-01');
console.log(date.isLeapYear());

Ограничения и особенности регистрации

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

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

Совместимость с tree-shaking

ESM-импорт плагинов позволяет сборщикам удалять неиспользуемый код. Однако сам факт вызова extend фиксирует использование функциональности, поэтому каждый подключённый плагин увеличивает итоговый размер бандла.

import dayjs from 'dayjs';
import customParseFormat from 'dayjs/plugin/customParseFormat';

dayjs.extend(customParseFormat);

Если плагин не используется в коде, но импортирован и зарегистрирован, он всё равно попадёт в сборку.

Внутренняя модель расширений

Каждый плагин получает доступ к объекту Day.js и может:

  • добавлять методы экземпляра;
  • расширять парсер строк дат;
  • внедрять новые форматы вывода;
  • изменять поведение вычислений.

Модель расширения основана на инъекции зависимостей, где ядро библиотеки остаётся неизменным, а функциональность добавляется внешними модулями.

Типовые сценарии подключения

Подключение UTC и временных зон:

import dayjs from 'dayjs';
import utc from 'dayjs/plugin/utc';
import timezone from 'dayjs/plugin/timezone';

dayjs.extend(utc);
dayjs.extend(timezone);

Поддержка относительного времени:

import relativeTime from 'dayjs/plugin/relativeTime';

dayjs.extend(relativeTime);

dayjs().fromNow();

Поддержка расширенного форматирования:

import advancedFormat from 'dayjs/plugin/advancedFormat';

dayjs.extend(advancedFormat);

dayjs().format('Q Do kkkk');

Контекст и область действия плагинов

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

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

Особенности работы в изолированных окружениях

В тестовых средах или serverless-функциях Day.js может инициализироваться многократно. В таких условиях регистрация плагинов выполняется при каждом запуске среды исполнения, что делает порядок подключения критичным для воспроизводимости поведения.

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

Оглавление