# js-joda date and time API guide for JavaScript

> js-joda gives JavaScript applications an immutable, domain-specific API for ISO dates, times, durations, periods, and zoned values. It is a good fit when date semantics matter, but timezone support and locale formatting require separate packages.

**js-joda/js-joda** — :clock2: Immutable date and time library for javascript

- Repository: https://github.com/js-joda/js-joda
- Website: http://js-joda.github.io/js-joda/
- Stars: 1,663 · Forks: 132
- Language: JavaScript
- License: NOASSERTION
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/js-joda-js-joda

## Why js-joda separates dates from native Date

js-joda addresses a specific modeling problem in JavaScript: the native Date object combines a date, a time, and a timezone into one mutable value. Code that needs only a calendar date can still receive or carry time and offset information it does not intend to represent. The library instead follows the ThreeTen domain model, the backport associated with Java SE 8 java.time.

That design produces separate classes for common cases. LocalDate represents a date without a time or timezone. LocalTime represents a time without a timezone. LocalDateTime combines both as they appear on a local wall clock, while ZonedDateTime includes a timezone. Instant represents a point on the timeline using seconds and nanoseconds from the 1970-01-01T00:00:00Z epoch.

This makes js-joda most relevant to applications that distinguish business dates from instants, recurring wall-clock times, or calendar periods. Birthdays and holidays fit LocalDate. Event timestamps that must be interpreted in an IANA timezone fit ZonedDateTime or Instant. MonthDay represents a recurring month and day, such as --12-03, without attaching an arbitrary year.

The library is immutable. Operations return new values instead of changing the receiver, which aligns with pure functions and frameworks such as React and Flux. The README also describes the implementation as a standalone date and time library rather than syntactic sugar around native Date. That is the main architectural distinction when comparing it with wrapper-oriented libraries such as moment or date-utils.

## js-joda package boundaries for core, timezone, locale, and extra

The repository is a monorepo containing four published packages with distinct responsibilities. @js-joda/core contains the ThreeTen classes and API. It is enough for the first LocalDate example, but it is not the complete package set for every time-related requirement.

Timezone calculation is isolated in @js-joda/timezone. According to the README, that package implements timezone calculation based on the IANA Time Zone Database. A project working only with local date and time concepts may not need it, but code requiring named timezone rules needs more than the core value objects. The repository documentation does not provide a timezone package example in the README, so no loading or initialization sequence should be inferred from package names alone.

Locale-sensitive formatting and parsing live in @js-joda/locale. This separation is important because ISO parsing and locale-aware parsing solve different problems. @js-joda/extra contains the ThreeTen-Extra classes and API. A separate @js-joda/examples package exercises build artifacts in contexts such as webpack, Node, and browsers, but it is not described as the runtime package to install in an application.

The boundary makes dependency selection explicit. Teams should not add all four packages merely to parse a birthday as LocalDate. Conversely, a scheduler that combines ISO parsing, user-facing locale formatting, and named timezones has requirements outside @js-joda/core. Review each package's documentation before constructing its initialization, particularly where modules must be registered rather than simply imported.

## Installing @js-joda/core and performing a first LocalDate calculation

The README's Node.js tutorial begins with the core package only. This installation is sufficient for the documented first operation because it uses LocalDate without timezone or locale functionality.

Install the package with npm:

```bash
npm install @js-joda/core
```

The repository package is published under the scoped name @js-joda/core. After installation, import LocalDate with CommonJS as shown in the README, parse an ISO date, move it to the start of its day, and add two months:

```js
var LocalDate = require('@js-joda/core').LocalDate;

var d = LocalDate.parse('2012-12-24').atStartOfDay().plusMonths(2);
```

The README annotates the resulting value as 2013-02-24T00:00:00. Each call returns a value rather than modifying the preceding one, which means d represents the result of the chain. The operation also shows a practical distinction between value types: parsing begins with a date-only string, atStartOfDay adds the local time context used by the expression, and plusMonths performs calendar arithmetic.

For a first real use, retain d as a LocalDate-derived result and pass that result onward rather than reaching for a native Date conversion. The README does not show how to print d explicitly or add named timezones, so those details should be taken from the linked API and quick-start documentation rather than invented.

## ISO parsing, formatter customization, and operation semantics

js-joda includes parsers and formatters for ISO 8601 as specified by RFC 3339, according to the README. The domain types keep ISO calendar rules at the center of the API. Values such as Year, YearMonth, Month, MonthDay, and DayOfWeek represent narrower ISO concepts instead of treating every requirement as a full timestamp.

Calendar arithmetic is represented in two forms. Duration is a time-based quantity, such as 34.5 seconds. Period is a date-based quantity, such as two years, three months, and four days. This distinction matters when expressing business deadlines or recurring schedules. An elapsed interval measured in time and a change expressed in calendar fields should not be assumed to be interchangeable.

The library also documents customizable ISO parsers and formatters. The README does not include the customization calls or configuration objects, so the exact extension mechanism is not confirmed. Developers who need non-default parsing behavior should consult the API documentation rather than adapt the basic require example by assumption.

The claimed performance and bundle figures are README statements, not measurements reproduced for this review. The README gives 43 kB for the minified and compressed footprint, no third-party dependencies, and a claimed comparison of two to ten times faster than other JavaScript date libraries. It also says more than 1,700 ThreeTen test cases were ported. These figures can inform an initial review, but they do not replace checking the relevant release, build target, and application workload.

## Operational limits of js-joda's immutable ISO model

The most important limitation is package scope. @js-joda/core does not itself provide locale-specific formatting or IANA timezone calculation. Those capabilities are assigned to @js-joda/locale and @js-joda/timezone. A project can therefore install successfully and still lack the functionality its users expect.

Another boundary concerns compatibility. The contributing guide says pull requests and issues must match the ThreeTen backport API, and additional requested features will be rejected. This is sensible for keeping the JavaScript port aligned with its reference model, but it means a requested convenience method outside that model may not be accepted. js-joda is less suitable when the deciding requirement is a mutable API, a large unrelated formatting surface, or an extension defined by application-specific syntax.

The browser instructions also require choosing a CDN asset and loading a script with the global JSJoda name. The documented file names are dist/js-joda.min.js and dist/js-joda.js, with source maps available for development according to the README. Browser consumers must account for global script loading rather than assuming the Node.js CommonJS example is interchangeable.

Named timezones introduce another validation requirement. The core model can represent timezone-bearing concepts, while actual timezone calculation depends on a separate package. If historical offset transitions, daylight-saving behavior, or user-selected zones are central to the application, review the timezone package's documented data and initialization path before committing to the design.

## License, maintenance signals, and upgrade scope

The repository metadata identifies the root package license as BSD-3-Clause, and the README states that js-joda is released under the BSD 3-clause license. Contributions are also described as being licensed under that license. Because the repository also notes that ThreeTen-Backport informed the implementation, maintainers should read the actual LICENSE file rather than treating a short metadata label as the complete text.

The repository is not archived. Its last push was on 2026-10-11. The listed package releases are older: @js-joda/core@3.1.0, @js-joda/timezone@2.3.0, and @js-joda/locale@3.2.0+36.0.0 all have release dates of 2020-08-11. The difference means repository activity and published package versions should be checked separately.

The root package.json contains documentation build and coverage scripts, while the repository includes package directories, a lock file, a changelog, and release documentation. The README does not document a supported major-version migration procedure, and the source contains no application-level dependency contract that would guarantee compatibility across all packages. Upgrading means reviewing the changelog and package-specific release notes, then checking whether the code depends on ThreeTen API behavior that changed.

## Conclusion

Adopt js-joda when JavaScript code needs explicit date, time, duration, and period types with immutable operations. Do not choose it merely for lightweight formatting if you require built-in locale support or timezone calculations, because those belong in @js-joda/locale and @js-joda/timezone. Check the LICENSE file, confirm that the API scope remains compatible with ThreeTen, and verify the required package set before migration.

## FAQ

### How do I install js-joda in a Node.js project?

Install the core package with `npm install @js-joda/core`, then import `LocalDate` from `@js-joda/core`. Timezone and locale functionality use separate packages.

### What is the difference between @js-joda/core and @js-joda/timezone?

@js-joda/core contains the ThreeTen classes and API. @js-joda/timezone provides timezone calculation based on the IANA Time Zone Database.

### Does js-joda include locale-specific date formatting?

Locale-specific functionality is implemented in the separate @js-joda/locale package. The core package is not documented as the location for that functionality.

## Sources

- [Issues](https://github.com/js-joda/js-joda/issues)
- [js-joda/js-joda on GitHub](https://github.com/js-joda/js-joda)
- [Project website](http://js-joda.github.io/js-joda/)
- [README](https://github.com/js-joda/js-joda/blob/main/README.md)
- [Releases](https://github.com/js-joda/js-joda/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/js-joda-js-joda