Поддержка браузеров и Node.js

Библиотека js-joda разрабатывалась как кроссплатформенное решение для работы с датой и временем в экосистеме JavaScript. Архитектура библиотеки позволяет использовать единый API как в браузере, так и в серверной среде Node.js. Это особенно важно для приложений, где логика обработки времени должна одинаково работать на клиенте и сервере.

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

  • независимость от встроенного объекта Date;
  • отсутствие привязки к DOM API;
  • модульная структура;
  • совместимость с CommonJS и ES Modules;
  • возможность подключения полифиллов для старых окружений.

Поддержка Node.js

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

Современные версии Node.js полностью поддерживают библиотеку без дополнительных настроек. Основное требование — наличие поддержки ES2015+.

Практически это означает:

Версия Node.js Поддержка
Node.js 18+ Полная
Node.js 16 Полная
Node.js 14 Полная
Node.js 12 Ограниченно
Node.js < 10 Не рекомендуется

Для актуальных проектов рекомендуется использовать LTS-версии Node.js.

Установка в Node.js

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

npm install @js-joda/core

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

yarn add @js-joda/core

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

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

const { LocalDate } = require('@js-joda/core');

const date = LocalDate.now();

console.log(date.toString());

Такой формат часто используется в:

  • старых Express-приложениях;
  • legacy-сервисах;
  • проектах без ESM;
  • серверных скриптах.

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

Современные приложения используют ESM-синтаксис:

import { LocalDate } from '@js-joda/core';

const date = LocalDate.now();

console.log(date.toString());

Для включения ESM в Node.js необходимо:

{
  "type": "module"
}

в файле package.json.

Работа в TypeScript

Библиотека хорошо интегрируется с TypeScript.

Пример:

import { LocalDate } from '@js-joda/core';

const date: LocalDate = LocalDate.now();

console.log(date.year());

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

  • строгая типизация;
  • автодополнение IDE;
  • безопасная работа с временными API;
  • уменьшение ошибок преобразования дат.

Поддержка браузеров

Общая совместимость

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

Браузер Поддержка
Chrome Полная
Firefox Полная
Safari Полная
Edge Полная
Opera Полная

Поддержка обеспечивается благодаря использованию стандартов ES2015.

Старые браузеры

Некоторые старые браузеры требуют полифиллы:

Браузер Особенности
Internet Explorer 11 Требуются полифиллы
Старые Android WebView Возможны ограничения
Safari 9 Частичная поддержка

Основные проблемы старых браузеров:

  • отсутствие Symbol;
  • отсутствие Map;
  • отсутствие Set;
  • неполная поддержка классов;
  • отсутствие iterator API.

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

Для совместимости со старыми браузерами применяется Babel.

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

npm install --save-dev @babel/core @babel/preset-env babel-loader

Конфигурация:

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "ie": "11"
        }
      }
    ]
  ]
}

Полифиллы

core-js

Чаще всего используется библиотека core-js.

Установка:

npm install core-js

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

import 'core-js/stable';

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

Подключение UMD-сборки

Библиотеку можно подключать напрямую через <script>:

<script src="https://unpkg.com/@js-joda/core/dist/js-joda.min.js"></script>

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

<script>
    const date = JSJoda.LocalDate.now();

    console.log(date.toString());
</script>

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

  • небольших приложений;
  • демонстраций;
  • playground-сред;
  • обучающих проектов.

Работа с bundlers

Webpack

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

npm install webpack webpack-cli --save-dev

Импорт:

import { ZonedDateTime } from '@js-joda/core';

Webpack корректно обрабатывает библиотеку без специальных loader-настроек.

Vite

Vite полностью совместим с js-joda.

Пример:

import { LocalTime } from '@js-joda/core';

console.log(LocalTime.now().toString());

Дополнительная конфигурация обычно не требуется.

Rollup

Пример подключения:

import resolve from '@rollup/plugin-node-resolve';

export default {
    input: 'src/main.js',
    output: {
        file: 'bundle.js',
        format: 'esm'
    },
    plugins: [resolve()]
};

Tree Shaking

Архитектура библиотеки поддерживает tree shaking.

Это означает:

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

Пример:

import { LocalDate } from '@js-joda/core';

В bundle не будут включены:

  • ZonedDateTime;
  • Period;
  • Duration;
  • другие неиспользуемые компоненты.

Размер библиотеки

Размер зависит от:

  • используемых модулей;
  • минификации;
  • tree shaking;
  • gzip-сжатия.

Примерная оценка:

Модуль Размер
@js-joda/core Небольшой
@js-joda/timezone Средний
locale-модули Дополнительно

Модуль временных зон значительно увеличивает размер сборки, поскольку содержит данные TZDB.

Поддержка временных зон

Базовый пакет

Пакет @js-joda/core не содержит полной базы временных зон.

Для работы с timezone используется:

npm install @js-joda/timezone

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

import '@js-joda/timezone';

import { ZonedDateTime, ZoneId } from '@js-joda/core';

const zoned = ZonedDateTime.now(
    ZoneId.of('Europe/Berlin')
);

console.log(zoned.toString());

Использование timezone в браузере

В браузере требуется подключение timezone-модуля:

import '@js-joda/timezone';

Без этого:

ZoneId.of('Europe/Berlin');

может вызвать ошибку отсутствия данных временной зоны.

Поддержка Intl API

Библиотека может использовать возможности встроенного Intl.

Поддержка зависит от среды:

Среда Intl
Современные браузеры Да
Node.js 18+ Да
Старые браузеры Частично

SSR и серверный рендеринг

Библиотека хорошо подходит для SSR-фреймворков:

  • Next.js
  • Nuxt
  • SvelteKit

Причины:

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

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

Пример:

import { LocalDate } from '@js-joda/core';

function App() {
    const today = LocalDate.now();

    return <div>{today.toString()}</div>;
}

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

import { LocalDateTime } from '@js-joda/core';

export default {
    setup() {
        const now = LocalDateTime.now();

        return { now };
    }
};

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

import { Component } from '@angular/core';
import { LocalDate } from '@js-joda/core';

@Component({
  selector: 'app-root',
  template: `{{ date }}`
})
export class AppComponent {
  date = LocalDate.now().toString();
}

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

Библиотека может работать и в Deno, однако поддержка зависит от способа импорта.

Пример:

import { LocalDate } from "npm:@js-joda/core";

console.log(LocalDate.now().toString());

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

Bun также поддерживает библиотеку:

import { Instant } from '@js-joda/core';

console.log(Instant.now().toString());

Проблемы совместимости

Смешивание с Date

Частая проблема — смешивание API Date и js-joda:

const jsDate = new Date();

и:

const localDate = LocalDate.now();

имеют принципиально разные модели времени.

Различия между средами

Некоторые различия могут возникать из-за:

  • локали ОС;
  • системной временной зоны;
  • ICU-конфигурации Node.js;
  • различий реализации Intl.

ICU в Node.js

Для корректной интернационализации иногда требуется full-icu.

Проверка:

console.log(Intl.DateTimeFormat.supportedLocalesOf(['ru']));

Запуск с full-icu:

node --icu-data-dir=node_modules/full-icu app.js

Поддержка ESM и CJS одновременно

Многие проекты постепенно мигрируют с CommonJS на ESM. js-joda поддерживает оба формата, что облегчает миграцию.

Возможны сценарии:

Формат проекта Поддержка
CommonJS Да
ES Modules Да
Mixed mode Ограниченно

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

const module = await import('@js-joda/core');

const date = module.LocalDate.now();

console.log(date.toString());

Такой подход полезен для:

  • lazy loading;
  • code splitting;
  • динамической загрузки модулей.

Поддержка Web Workers

Библиотека работает внутри Web Workers без ограничений:

import { Instant } from '@js-joda/core';

postMessage(Instant.now().toString());

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

Electron полностью поддерживает js-joda как в:

  • renderer process;
  • main process;
  • preload scripts.

Производительность в разных средах

Производительность зависит от:

  • движка JavaScript;
  • оптимизации JIT;
  • объёма операций;
  • использования timezone API.

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

Среда Производительность
Node.js (V8) Высокая
Chrome Высокая
Firefox Средняя
Safari Средняя

Отладка в браузере

Объекты js-joda удобно отображаются в DevTools:

console.log(LocalDate.now());

Вывод:

2026-05-24

Поддержка JSON

Сериализация работает одинаково в браузере и Node.js:

const date = LocalDate.now();

JSON.stringify({
    date: date.toString()
});

Результат:

{
  "date": "2026-05-24"
}

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

Сервер Node.js

app.get('/api/date', (req, res) => {
    res.json({
        now: Instant.now().toString()
    });
});

Клиент браузера

fetch('/api/date')
    .then(r => r.json())
    .then(data => {
        console.log(data.now);
    });

Рекомендации по совместимости

Для современных приложений

Рекомендуемая конфигурация:

  • Node.js 18+;
  • ESM;
  • Vite/Webpack;
  • TypeScript;
  • современные браузеры.

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

Необходимы:

  • Babel;
  • core-js;
  • transpilation ES2015;
  • проверка timezone API.

Проверка поддержки среды

Пример базовой проверки:

function supportsJsJoda() {
    return (
        typeof Map !== 'undefined' &&
        typeof Set !== 'undefined' &&
        typeof Symbol !== 'undefined'
    );
}

Изоморфные приложения

js-joda особенно хорошо подходит для изоморфных приложений, где один и тот же код выполняется:

  • на сервере;
  • в браузере;
  • в edge runtime.

Пример общей модели:

export function createDate() {
    return LocalDate.now();
}

Функция может одинаково использоваться:

  • в Node.js;
  • в React;
  • в SSR;
  • в браузере;
  • в serverless-функциях.
Оглавление