Guides / Start

Overview

Readable, immutable dates and times built on the browser's Temporal and Intl APIs.

Modern JavaScript engines include Temporal for calendar and time-zone math alongside Intl for localized formatting. Native Dates wraps those built-in APIs in plain English with zero runtime dependencies.

import { date, now, today } from 'native-dates';

const due = today().plus(2, 'weeks');
const standup = date('2026-11-16')
  .at('9:30am', 'America/Los_Angeles')
  .in('Europe/Berlin');

Because the runtime already carries the IANA time-zone database and locale rules, every region and language works out of the box. Your bundle never downloads extra zone or locale tables.

Separate types for separate jobs

JavaScript’s built-in Date uses one object whether you mean a holiday, an opening hour, or a database timestamp. Native Dates gives each concept its own type so values only carry the fields that make sense for them:

• CalendarDate for a calendar day like May 10, 2026, unaffected by time zones
• Time for a time of day like 9:30 AM, wrapping cleanly at midnight
• DateTime for a specific moment paired with a time zone
• Duration for a length of time like 90 minutes or 2 weeks

Measuring the gap between two moments or dates gives you a Duration directly:

import { datetime, now } from 'native-dates';

const deadline = datetime('2027-01-01T00:00:00Z');
now().until(deadline).format('long');

Read Types of time next to see how to pick between them and move from one to another.

Immutable values

Every instance is immutable. Calling methods like plus() or in() always returns a new value and leaves the original untouched.

Passing a date into a helper or UI component can never mutate caller state behind your back:

const original = date('2026-11-16').at('9:30am', 'America/Los_Angeles');
const moved = original.plus(1, 'hour');

original.text; // 'Nov 16, 2026, 9:30 AM PST'
moved.text; // 'Nov 16, 2026, 10:30 AM PST'

Every value also includes a .text property with a human-readable summary. Logging an instance in Node or browser DevTools shows what it means right away without clicking getters:

import { time } from 'native-dates';

date('2026-05-10').text; // 'May 10, 2026'
time('9:30am').text; // '9:30 AM'

Lean core and opt-in plugins

The core native-dates package stays small. It covers creation, time zones, calendar math, comparisons, durations, and localized presets.

Specialized tools live in @native-dates/plugins as individual subpath imports. You only bundle the features your project actually uses:

import '@native-dates/plugins/ranges';
import '@native-dates/plugins/tokens';
import { date } from 'native-dates';

const sprint = date('2026-11-02').to(2, 'weeks');
sprint.start.format('YYYY-MM-DD'); // '2026-11-02'

Head to Installation to install the package, support older runtimes, and configure app-wide defaults.