Установка и подключение

Js-joda — библиотека для работы с датой и временем в JavaScript, основанная на API java.time из Java 8. Главная цель библиотеки — предоставить строгую, предсказуемую и безопасную модель работы со временем без типичных проблем стандартного объекта Date.

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

  • неизменяемые объекты даты и времени;
  • строгую типизацию временных сущностей;
  • корректную работу с часовыми поясами;
  • удобные операции форматирования и вычислений;
  • отсутствие скрытых преобразований времени.

Js-joda особенно полезна в крупных приложениях, backend-разработке, финансовых системах, расписаниях, CRM и любых проектах, где требуется точная работа со временем.

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

Наиболее распространённый способ подключения библиотеки — установка через npm.

Установка основного пакета

npm install @js-joda/core

После установки становятся доступны базовые классы:

  • LocalDate
  • LocalTime
  • LocalDateTime
  • ZonedDateTime
  • Duration
  • Period
  • Instant
  • ZoneId
  • DateTimeFormatter

Подключение в CommonJS

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

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

const date = LocalDate.now();

console.log(date.toString());

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

В современных проектах применяется синтаксис import.

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

const date = LocalDate.now();

console.log(date.toString());

Структура библиотеки

Js-joda разделена на несколько пакетов.

Основной пакет

npm install @js-joda/core

Содержит все базовые классы и API.

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

npm install @js-joda/timezone

Добавляет полноценную поддержку IANA timezone database.

Пример:

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

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

console.log(date.toString());

Без пакета @js-joda/timezone многие временные зоны недоступны.

Дополнительные форматы

npm install @js-joda/locale

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

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

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

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

const current = LocalDate.now();

console.log(current);

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

2026-05-24

Дата будет соответствовать текущему дню системы.

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

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

Js-joda можно подключить напрямую в HTML.

<script src="https://cdn.jsdelivr.net/npm/@js-joda/core/dist/js-joda.min.js"></script>

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

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

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

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

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

Установка

npm install @js-joda/core

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

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

const now = LocalDateTime.now();

console.log(now.toString());

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

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

Установка

npm install @js-joda/core

Импорт

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

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

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

Js-joda имеет встроенную поддержку TypeScript.

Установка

npm install @js-joda/core

Пример

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

const date: LocalDate = LocalDate.now();

console.log(date.toString());

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

Проверка доступных классов

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

import {
    LocalDate,
    LocalTime,
    LocalDateTime,
    ZonedDateTime,
    Duration
} from '@js-joda/core';

Подключение только необходимых модулей

Js-joda поддерживает tree shaking.

Это позволяет импортировать только используемые классы.

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

В итоговый bundle не попадут неиспользуемые части библиотеки.

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

Библиотека совместима с Babel без специальной настройки.

Пример .babelrc:

{
  "presets": ["@babel/preset-env"]
}

Минимальные требования среды

Js-joda поддерживает:

  • современные браузеры;
  • Node.js;
  • TypeScript;
  • сборщики Webpack, Rollup, Vite, Parcel;
  • ECMAScript Modules;
  • CommonJS.

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

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

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

Поэтому для работы с:

  • Europe/Moscow
  • Asia/Tokyo
  • America/New_York

необходимо установить дополнительный модуль.

Установка timezone-пакета

npm install @js-joda/timezone

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

import '@js-joda/timezone';

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

Проверка работы timezone

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

import '@js-joda/timezone';

const tokyo = ZonedDateTime.now(
    ZoneId.of('Asia/Tokyo')
);

console.log(tokyo.toString());

Ошибка отсутствующей временной зоны

Типичная ошибка:

unsupported ZoneId

Причина — не подключён пакет @js-joda/timezone.

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

Пример отдельного файла

index.js

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

const now = LocalDateTime.now();

console.log(now.toString());

Запуск

node index.js

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

Установка

npm install @js-joda/core

Компонент React

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

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

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

export default App;

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

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

export default {
    setup() {
        const today = LocalDate.now();

        return {
            today
        };
    }
};

Использование в 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();
}

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

Основной пакет имеет сравнительно небольшой размер.

Дополнительные timezone-данные увеличивают bundle, поэтому:

  • timezone подключают только при необходимости;
  • рекомендуется использовать tree shaking;
  • желательно избегать импорта неиспользуемых модулей.

Отличия от стандартного Date

После подключения Js-joda становится доступна совершенно другая модель работы со временем.

Standard Date

const date = new Date();

Проблемы:

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

Js-joda

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

const date = LocalDate.now();

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

  • неизменяемость объектов;
  • строгие типы;
  • предсказуемость;
  • ISO-совместимость;
  • отсутствие скрытых преобразований.

Проверка версии библиотеки

Через npm

npm list @js-joda/core

Через package.json

{
  "dependencies": {
    "@js-joda/core": "^5.6.1"
  }
}

Удаление библиотеки

npm

npm uninstall @js-joda/core

yarn

yarn remove @js-joda/core

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

Установка

yarn add @js-joda/core

Установка timezone

yarn add @js-joda/timezone

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

Установка

pnpm add @js-joda/core

Установка timezone

pnpm add @js-joda/timezone

Типичная структура проекта

project/
│
├── src/
│   ├── date/
│   │   ├── formatter.js
│   │   ├── timezone.js
│   │   └── parser.js
│   │
│   └── app.js
│
├── package.json
└── node_modules/

Рекомендуемый отдельный модуль для даты

Во многих проектах создают единый файл для работы со временем.

// date.js

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

export {
    LocalDate,
    LocalDateTime,
    DateTimeFormatter
};

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

import {
    LocalDate
} from './date.js';

const date = LocalDate.now();

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

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

import '@js-joda/timezone';

console.log(
    ZoneId.of('Europe/London')
);

Основные подключаемые сущности

Класс Назначение
LocalDate Дата без времени
LocalTime Время без даты
LocalDateTime Дата и время
ZonedDateTime Дата, время и timezone
Instant Точка времени UTC
Duration Продолжительность
Period Период
DateTimeFormatter Форматирование

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

npm install @js-joda/core @js-joda/timezone
import {
    LocalDate,
    ZonedDateTime,
    ZoneId
} from '@js-joda/core';

import '@js-joda/timezone';

Такой набор покрывает большинство задач в веб-разработке и backend-приложениях.

Оглавление