Immutable date and time library for javascript

npm version Build Status Sauce Test Status Coverage Status Tested node version

Sauce Test Status


Why yet another javascript date and time library

The threeten domain models

Dates and Times

Duration and Period

Additional value types

Getting started


Install joda using npm

npm install js-joda

Then require it to any module

var LocalDate = require('js-joda').LocalDate;

var d = LocalDate.parse('2012-12-24').atStartOfDay().plusMonths(2); // 2013-02-24T00:00:00


To use js-joda from a browser, download either dist/js-joda.min.js or dist/js-joda.js (with sourcemaps for development)

Then add it as a script tag to your page

<script src="js-joda.min.js"></script>
    var LocalDate = JSJoda.LocalDate;
    var d = LocalDate.parse('2012-12-24').atStartOfDay().plusMonths(2); // 2013-02-24T00:00:00



Milestone 1 core domains (reached with version v1.0.0)

Support for the domain models LocalDate, LocalDateTime, ZonedDateTime, Instant, Duration and Period converting from and to ISO8601. ZonedDateTime (without support for loading iana time-zone databases) currently supports only fixed offsets like UTC or UTC+02:00 and the system default time zone.

Milestone 2 iana timezone support (reached with version v1.2.0)

Add iana timezone database support to js-joda. Implement handling of Daylight saving transitions mainly in ZonedDateTime.

For having access to the iana timezone database, the plugin js-joda-timezone is required. It is providing an implementation of the ZoneRulesProvider and contains the iana timezone database.

Milestone 3 locale support

Add locale support.

Extend pattern parser/ formatter for text with locale support.

Future Milestones


Contributions are always welcome. Before contributing please read the code of conduct & search the issue tracker. We use GitHub issues. Your issue may have already been discussed or fixed. To contribute, fork js-joda, commit your changes, & send a pull request.

By contributing to js-joda, you agree that your contributions will be licensed under its BSD license.

Note that pull requests and issues will only be considered so far as matching the threeten backport API. Additional requested features will be rejected.


Joda time is the base for JSR-310 that became part of Java SE 8 in the java.time package. JSR-310 is a new implementation with an API ‘inspired by Joda-Time’ but improvements on some design flaws (see

js-joda is using the ThreeTen-Backport implementation ( as a reference base for implementation. This allows us to release js-joda under the BSD License while the OpenJDK java.time implementation is under GNU GPL+linking exception. The API of the ThreeTen-Backport is mostly identical to the official Java SE 8 API from the view of our javascript port.

The API of this project (as far as possible with javascript), a lot of implementation details and documentation are just copied but never equalled.