dayjs

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

weekly downloads34.7M

versionv1.11.19

licenseMIT

categoryutility

dayjsdatetimeimmutablemoment

Overview

Day.js is a minimalist JavaScript library for working with dates and times, weighing only 2KB minified and gzipped. It was created as a lightweight alternative to Moment.js, offering an almost identical API that makes migration straightforward while dramatically reducing bundle size. The library handles common date operations including parsing, validation, manipulation, formatting, and comparison through a chainable, developer-friendly interface.

The core philosophy centers on immutability—every operation returns a new Day.js instance rather than modifying the original, preventing unintended side effects that plague mutable date libraries. This design choice aligns with modern JavaScript practices and makes Day.js safe to use in React, Vue, and other reactive frameworks where mutation tracking matters. With over 34 million weekly downloads, it has become a standard choice for projects prioritizing bundle size without sacrificing date manipulation capabilities.

Day.js uses a plugin architecture to keep the core tiny. Advanced features like UTC/timezone support, relative time formatting, locale-specific formatting, and calendar functions are available as optional plugins. This allows developers to include only what they need, though it means the base library lacks some functionality that comes standard in heavier alternatives. The library works seamlessly in both Node.js and browser environments, supports tree-shaking, and maintains compatibility with modern build tools.

Typical users include teams migrating from deprecated Moment.js, developers building size-conscious SPAs, mobile web applications where every kilobyte affects load time, and projects that need basic date operations without heavyweight dependencies. It's particularly popular in the React ecosystem and among developers who prefer Moment's API style but need modern performance characteristics.

Quick Start

typescript

import dayjs from 'dayjs';
import utc from 'dayjs/plugin/utc';
import timezone from 'dayjs/plugin/timezone';
import relativeTime from 'dayjs/plugin/relativeTime';

dayjs.extend(utc);
dayjs.extend(timezone);
dayjs.extend(relativeTime);

// Parse and format dates
const meetingDate = dayjs('2024-03-15 14:30');
console.log(meetingDate.format('MMMM D, YYYY [at] h:mm A'));
// "March 15, 2024 at 2:30 PM"

// Immutable manipulation - original unchanged
const tomorrow = dayjs().add(1, 'day');
const nextWeek = tomorrow.add(6, 'day').startOf('day');
console.log(nextWeek.format('YYYY-MM-DD'));

// Date comparisons and validation
const startDate = dayjs('2024-01-01');
const endDate = dayjs('2024-12-31');
const isValid = endDate.isAfter(startDate);
const daysDiff = endDate.diff(startDate, 'day');
console.log(`Valid range: ${isValid}, Days: ${daysDiff}`);

// Timezone conversions
const utcTime = dayjs.utc('2024-03-15 14:30');
const tokyo = utcTime.tz('Asia/Tokyo');
const newYork = utcTime.tz('America/New_York');
console.log(`Tokyo: ${tokyo.format()}, NY: ${newYork.format()}`);

// Relative time for UI
const posted = dayjs().subtract(3, 'hour');
console.log(posted.fromNow()); // "3 hours ago"

// Chaining for complex operations
const quarterStart = dayjs()
  .startOf('quarter')
  .add(1, 'month')
  .endOf('month');
console.log(quarterStart.format('YYYY-MM-DD'));

Use Cases

Form validation with date ranges: Validate user-submitted dates in booking forms, event schedulers, or registration systems. Check if dates fall within allowed ranges, ensure end dates come after start dates, or restrict selections to business days using comparison methods like isBefore() and isAfter().

Displaying relative timestamps: Show 'posted 2 hours ago' or 'updated 3 days ago' in social feeds, comment sections, or activity logs. The relativeTime plugin converts absolute timestamps into human-readable relative formats that automatically update as time passes.

Multi-timezone event scheduling: Convert and display event times across different timezones for international applications, calendar apps, or booking systems. Use the timezone and utc plugins to handle timezone conversions without native Date object pitfalls.

Report generation with date arithmetic: Calculate date ranges for analytics dashboards, financial reports, or data exports. Add/subtract time units to generate week-over-week comparisons, quarter boundaries, or rolling 30-day windows using immutable manipulation methods.

Localized date formatting: Display dates in user-preferred formats for international applications. Load locale plugins to format dates according to regional conventions—German 'DD.MM.YYYY', Japanese '年月日', or custom business formats—without manual string manipulation.

Pros & Cons

Pros

+Extremely small footprint at 2KB makes it ideal for bundle-size-conscious applications and mobile web
+Nearly drop-in replacement for Moment.js with 90%+ API compatibility, minimizing migration effort
+Immutable API prevents bugs caused by unintended mutations and works naturally with React/Vue
+Plugin system keeps core tiny while offering opt-in features like timezone support and localization
+Chainable methods provide clean, readable code for complex date transformations

Cons

−Plugin requirement for basic features like UTC or relative time adds configuration overhead
−Less powerful than Luxon for timezone-heavy applications since it doesn't leverage native Intl API
−Smaller ecosystem than date-fns means fewer utility functions and community plugins available
−Documentation can be sparse for edge cases compared to more mature libraries
−Not tree-shakable at the method level—you import the entire core even if using few features

Alternatives

date-fnsv4.1.0

Modern JavaScript date utility library

utility

43.3M / week

luxonv3.7.2

Immutable date wrapper

utilitydateimmutable

20.4M / week

Comparisons

date-fns vs dayjs

utility

Install

bash

npm install dayjs

bash

pnpm add dayjs

bash

bun add dayjs

Overview

Quick Start

typescript

import dayjs from 'dayjs';
import utc from 'dayjs/plugin/utc';
import timezone from 'dayjs/plugin/timezone';
import relativeTime from 'dayjs/plugin/relativeTime';

dayjs.extend(utc);
dayjs.extend(timezone);
dayjs.extend(relativeTime);

// Parse and format dates
const meetingDate = dayjs('2024-03-15 14:30');
console.log(meetingDate.format('MMMM D, YYYY [at] h:mm A'));
// "March 15, 2024 at 2:30 PM"

// Immutable manipulation - original unchanged
const tomorrow = dayjs().add(1, 'day');
const nextWeek = tomorrow.add(6, 'day').startOf('day');
console.log(nextWeek.format('YYYY-MM-DD'));

// Date comparisons and validation
const startDate = dayjs('2024-01-01');
const endDate = dayjs('2024-12-31');
const isValid = endDate.isAfter(startDate);
const daysDiff = endDate.diff(startDate, 'day');
console.log(`Valid range: ${isValid}, Days: ${daysDiff}`);

// Timezone conversions
const utcTime = dayjs.utc('2024-03-15 14:30');
const tokyo = utcTime.tz('Asia/Tokyo');
const newYork = utcTime.tz('America/New_York');
console.log(`Tokyo: ${tokyo.format()}, NY: ${newYork.format()}`);

// Relative time for UI
const posted = dayjs().subtract(3, 'hour');
console.log(posted.fromNow()); // "3 hours ago"

// Chaining for complex operations
const quarterStart = dayjs()
  .startOf('quarter')
  .add(1, 'month')
  .endOf('month');
console.log(quarterStart.format('YYYY-MM-DD'));

Use Cases

Pros & Cons

Pros

+Extremely small footprint at 2KB makes it ideal for bundle-size-conscious applications and mobile web
+Nearly drop-in replacement for Moment.js with 90%+ API compatibility, minimizing migration effort
+Immutable API prevents bugs caused by unintended mutations and works naturally with React/Vue
+Plugin system keeps core tiny while offering opt-in features like timezone support and localization
+Chainable methods provide clean, readable code for complex date transformations

Cons

−Plugin requirement for basic features like UTC or relative time adds configuration overhead
−Less powerful than Luxon for timezone-heavy applications since it doesn't leverage native Intl API
−Smaller ecosystem than date-fns means fewer utility functions and community plugins available
−Documentation can be sparse for edge cases compared to more mature libraries
−Not tree-shakable at the method level—you import the entire core even if using few features