Home Reference Source Repository

Immutable data and time library for javascript

npm version Build Status Coverage Status


js-joda, a port of the ThreeTen immutable data and time library to javascript. It provides a simple and clean API based on the ISO8601 calendar. Joda-Time (the predecessor project) used to be the de facto standard date and time library for Java and is the base for JSR-310 that became part of Java SE 8 in the java.time package.

Why yet another javascript date and time library

Getting started

The library is in a very early state, far away from productive. But you are very welcome to play around with js-joda and to give your feedback. Please check the tests and the API Documentation for the current state of development.


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

Our current plan is to have a first milestone with LocalDate, LocalDateTime, Instant, Duration and Period working. The result of the first milestone will be a fully functional Date/Time library, converting from and to ISO8601, with UTC and system default timezone.

Future Milestones

Any further timezone converting and localization is not part of the first milestone and will be saved for later. This might also be an extra package to reduce library size if Timezone functionality is not needed.


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 http://blog.joda.org/2009/11/why-jsr-310-isn-joda-time_4941.html)

js-joda is using the ThreeTen-Backport implementation (http://www.threeten.org/threetenbp/) 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.