luxon

Immutable date wrapper

weekly downloads20.4M

versionv3.7.2

licenseMIT

categoryutility

dateimmutable

Overview

Luxon is a mature JavaScript library that wraps native Date objects with an immutable, chainable API designed for production applications. Created by the Moment.js team as their recommended successor, it solves the pain points of JavaScript's built-in Date implementation—mutability, poor timezone handling, inconsistent parsing, and limited formatting options—without requiring polyfills or external locale files.

The library centers around three core types: DateTime for point-in-time values with full timezone and locale awareness, Duration for representing time spans (like "3 days" or "2 hours"), and Interval for date ranges with built-in math operations. Every operation returns a new instance rather than mutating existing objects, eliminating entire classes of bugs common in date manipulation code.

With over 20 million weekly downloads, Luxon is widely adopted in enterprise applications, scheduling systems, and any JavaScript project requiring reliable date arithmetic. It leverages the browser's native Intl API for localization and IANA timezone database for accurate timezone conversions, making it lighter than alternatives that bundle their own timezone data. The library works seamlessly across Node.js and all modern browsers with ESM, CommonJS, and UMD support.

Luxon is actively maintained with a stable 3.x release line and a clear roadmap for version 4.0 focused on build optimization. Its comprehensive documentation and TypeScript definitions make it accessible for teams migrating from Moment.js or building new applications that need bulletproof date handling.

Quick Start

typescript

import { DateTime, Duration, Interval } from 'luxon';

// Create DateTime instances with timezone awareness
const now = DateTime.now();
const userMeeting = DateTime.fromISO('2025-03-15T14:30:00', { zone: 'America/Los_Angeles' });
const localMeeting = userMeeting.setZone('Europe/London');

console.log(localMeeting.toFormat('fff')); // "March 15, 2025, 10:30 PM GMT"

// Date arithmetic with immutable operations
const deadline = DateTime.now()
  .plus({ days: 7 })
  .endOf('day')
  .minus({ hours: 1 });

console.log(deadline.toISO()); // ISO string for 11 PM, 7 days from now

// Calculate duration between dates
const projectStart = DateTime.fromISO('2025-01-01');
const daysElapsed = now.diff(projectStart, 'days').days;
const detailedDiff = now.diff(projectStart, ['months', 'days', 'hours']);

console.log(`${Math.floor(daysElapsed)} days into project`);
console.log(detailedDiff.toObject()); // { months: 2, days: 13, hours: 5 }

// Work with intervals and validate date ranges
const vacation = Interval.fromDateTimes(
  DateTime.fromISO('2025-07-01'),
  DateTime.fromISO('2025-07-14')
);

const tripDate = DateTime.fromISO('2025-07-10');
console.log(vacation.contains(tripDate)); // true
console.log(vacation.length('days')); // 13

// Parse various formats and handle invalid dates
const parsed = DateTime.fromFormat('12/25/2025', 'MM/dd/yyyy');
if (parsed.isValid) {
  console.log(parsed.toLocaleString(DateTime.DATE_FULL)); // "December 25, 2025"
} else {
  console.error(parsed.invalidReason);
}

Use Cases

Scheduling and calendar applications: Build booking systems, event planners, or meeting schedulers that correctly handle timezone conversions across global users. Luxon's setZone() method and Interval type make it straightforward to calculate availability windows, detect overlaps, and display times in each user's local timezone without manual offset math.

Data analytics and reporting: Parse timestamps from APIs or databases in various formats (ISO, RFC, SQL, Unix), perform date arithmetic like grouping by week or month, and calculate durations between events. The diff() method provides human-readable time spans while maintaining precision for aggregations.

Internationalized applications: Display dates and times according to user locale preferences without bundling locale files. Luxon uses the browser's Intl API to format dates in any language and calendar system, supporting relative time formatting ("3 hours ago") and custom format tokens.

Form validation and date pickers: Validate user input with built-in parsing that detects invalid dates, handle date range selection with Interval objects, and ensure submitted dates respect business rules like "must be a weekday" or "within 30 days" using Luxon's fluent API.

Recurring event systems: Calculate occurrences of repeating events by combining Duration arithmetic with DateTime methods. Generate a series of dates, skip weekends or holidays, and handle edge cases like "last Friday of each month" with readable, maintainable code.

Pros & Cons

Pros

+Immutable API prevents accidental mutations and side effects, making date logic more predictable and easier to debug
+Native IANA timezone support without external data files, using the browser/Node.js built-in timezone database for accurate conversions
+Comprehensive type system (DateTime, Duration, Interval) covers all common date scenarios with intuitive methods and excellent TypeScript definitions
+Mature successor to Moment.js with active maintenance, 20M+ weekly downloads, and extensive real-world battle-testing
+Leverages native Intl API for localization, reducing bundle size and supporting all locales without manual imports

Cons

−Larger bundle size (~70KB minified) compared to modular alternatives like date-fns, though tree-shaking helps in version 4.x roadmap
−Steeper learning curve than native Date for simple use cases—overkill if you only need basic date display without timezone handling
−Requires modern browser environments for full Intl/timezone support; older browsers need polyfills that increase payload
−Chainable API encourages long method chains that can be harder to debug when intermediate values need inspection
−No built-in support for relative time parsing ("in 3 days") or humanized durations without custom formatting logic

Alternatives

date-fnsv4.1.0

Modern JavaScript date utility library

utility

43.3M / week

dayjsv1.11.19

2KB immutable date time library alternative to Moment.js with the same modern API

utilitydayjsdate

34.7M / week

Comparisons

date-fns vs luxon

utility

Install

bash

npm install luxon

bash

pnpm add luxon

bash

bun add luxon

Overview

Quick Start

typescript

import { DateTime, Duration, Interval } from 'luxon';

// Create DateTime instances with timezone awareness
const now = DateTime.now();
const userMeeting = DateTime.fromISO('2025-03-15T14:30:00', { zone: 'America/Los_Angeles' });
const localMeeting = userMeeting.setZone('Europe/London');

console.log(localMeeting.toFormat('fff')); // "March 15, 2025, 10:30 PM GMT"

// Date arithmetic with immutable operations
const deadline = DateTime.now()
  .plus({ days: 7 })
  .endOf('day')
  .minus({ hours: 1 });

console.log(deadline.toISO()); // ISO string for 11 PM, 7 days from now

// Calculate duration between dates
const projectStart = DateTime.fromISO('2025-01-01');
const daysElapsed = now.diff(projectStart, 'days').days;
const detailedDiff = now.diff(projectStart, ['months', 'days', 'hours']);

console.log(`${Math.floor(daysElapsed)} days into project`);
console.log(detailedDiff.toObject()); // { months: 2, days: 13, hours: 5 }

// Work with intervals and validate date ranges
const vacation = Interval.fromDateTimes(
  DateTime.fromISO('2025-07-01'),
  DateTime.fromISO('2025-07-14')
);

const tripDate = DateTime.fromISO('2025-07-10');
console.log(vacation.contains(tripDate)); // true
console.log(vacation.length('days')); // 13

// Parse various formats and handle invalid dates
const parsed = DateTime.fromFormat('12/25/2025', 'MM/dd/yyyy');
if (parsed.isValid) {
  console.log(parsed.toLocaleString(DateTime.DATE_FULL)); // "December 25, 2025"
} else {
  console.error(parsed.invalidReason);
}

Use Cases

Pros & Cons

Pros

+Immutable API prevents accidental mutations and side effects, making date logic more predictable and easier to debug
+Native IANA timezone support without external data files, using the browser/Node.js built-in timezone database for accurate conversions
+Comprehensive type system (DateTime, Duration, Interval) covers all common date scenarios with intuitive methods and excellent TypeScript definitions
+Mature successor to Moment.js with active maintenance, 20M+ weekly downloads, and extensive real-world battle-testing
+Leverages native Intl API for localization, reducing bundle size and supporting all locales without manual imports

Cons

−Larger bundle size (~70KB minified) compared to modular alternatives like date-fns, though tree-shaking helps in version 4.x roadmap
−Steeper learning curve than native Date for simple use cases—overkill if you only need basic date display without timezone handling
−Requires modern browser environments for full Intl/timezone support; older browsers need polyfills that increase payload
−Chainable API encourages long method chains that can be harder to debug when intermediate values need inspection
−No built-in support for relative time parsing ("in 3 days") or humanized durations without custom formatting logic