Day.js — Fast 2kB Immutable Date Library for JavaScript

Introduction

Day.js is a minimalist JavaScript date library that parses, validates, manipulates, and displays dates and times. It was designed as a drop-in replacement for Moment.js with a nearly identical API but at roughly 2kB minified and gzipped. Day.js uses immutable data structures, avoiding the mutation pitfalls that plagued Moment.js.

What Day.js Does

• Parses dates from strings, timestamps, Date objects, and ISO 8601 formats
• Formats and displays dates using familiar token patterns like YYYY-MM-DD
• Performs date arithmetic such as add, subtract, startOf, and endOf
• Compares dates with isBefore, isAfter, and isSame helpers
• Extends functionality through a rich plugin ecosystem covering time zones, relative time, and locales

Architecture Overview

Day.js wraps a native JavaScript Date object in a lightweight immutable wrapper. All mutation methods return new Day.js instances rather than modifying the original. The core library is intentionally small and delegates advanced features to optional plugins loaded via dayjs.extend(). Locale data is also loaded on demand, keeping the default bundle minimal.

Self-Hosting & Configuration

• Install via npm, yarn, or pnpm; also available as a CDN script
• Import plugins individually: import utc from 'dayjs/plugin/utc'
• Load locales on demand: import 'dayjs/locale/de' then dayjs.locale('de')
• Works in Node.js, browsers, and bundlers with full tree-shaking support
• TypeScript declarations are included out of the box

Key Features

• 2kB gzipped core with immutable API design
• Near-complete Moment.js API compatibility for easy migration
• 20+ official plugins including UTC, timezone, relative time, and duration
• Supports 100+ locales with on-demand loading
• Chainable API for readable date manipulation pipelines

Comparison with Similar Tools

• Moment.js — larger bundle (70kB), mutable API, now in maintenance mode
• Luxon — more opinionated with Intl-based formatting, larger footprint (~20kB)
• date-fns — functional tree-shakeable approach but requires importing individual functions
• Temporal (TC39) — upcoming native JavaScript API, not yet widely available

FAQ

Q: Can I migrate from Moment.js to Day.js without rewriting my code? A: In most cases yes. The core API is nearly identical. The main differences involve plugins for advanced features like time zones and durations.

Q: Does Day.js handle time zones? A: Yes, through the official utc and timezone plugins which use the IANA time zone database.

Q: Is Day.js suitable for server-side Node.js projects? A: Absolutely. It works in any JavaScript environment including Node.js, Deno, and Bun.

Q: How does Day.js achieve its small size? A: By keeping the core minimal and moving features like locales, relative time, and duration into separate plugins.

Sources

• https://github.com/iamkun/dayjs
• https://day.js.org/