Day.js — Fast 2KB Date Library for JavaScript

Introduction

Day.js is a minimalist JavaScript date library that parses, validates, manipulates, and displays dates and times. At just 2 KB gzipped it provides a Moment.js-compatible API without the bundle size overhead, making it ideal for modern front-end projects.

What Day.js Does

• Parses date strings, timestamps, and native Date objects into immutable Day.js instances
• Formats dates using familiar token patterns like YYYY-MM-DD HH:mm:ss
• Performs arithmetic: add, subtract, start/end of unit, diff between dates
• Compares dates with isBefore, isAfter, and isSame methods
• Extends functionality through an official plugin system for UTC, timezone, relative time, and more

Architecture Overview

Day.js wraps a native JavaScript Date object in a lightweight immutable wrapper. All mutation methods return new instances rather than modifying the original. The core ships only essential parsing and formatting logic. Advanced features like timezone support, ISO week, and localized relative time are loaded as tree-shakeable plugins, keeping the default bundle minimal.

Installation & Configuration

• Install via npm, yarn, pnpm, or load from a CDN
• Import the core module and register plugins as needed with dayjs.extend()
• Load locale files for internationalized date formatting across 100+ locales
• Works in Node.js, browsers, and edge runtimes
• TypeScript declarations are included out of the box

Key Features

• Immutable API prevents accidental date mutation bugs
• Plugin architecture keeps the core at 2 KB while supporting advanced use cases
• Moment.js-compatible API simplifies migration from Moment
• Locale support for over 100 languages with lazy-loaded locale files
• Chainable methods for readable date manipulation chains

Comparison with Similar Tools

• Moment.js — same API but 67 KB gzipped and mutable; Day.js is 2 KB and immutable
• date-fns — tree-shakeable function-based approach; Day.js uses a chainable OOP style
• Luxon — richer timezone and Intl support but larger bundle; Day.js covers most cases with plugins
• Temporal (TC39) — upcoming standard API; Day.js works today across all environments
• Native Date — no formatting or arithmetic helpers; Day.js adds those in a tiny package

FAQ

Q: Can Day.js handle timezones? A: Yes. Install the dayjs/plugin/utc and dayjs/plugin/timezone plugins, then use dayjs.tz() to parse and convert between zones.

Q: Is Day.js a drop-in replacement for Moment.js? A: For most use cases yes. The core API is intentionally compatible. Some advanced Moment features require enabling the corresponding Day.js plugin.

Q: Does Day.js support relative time like "3 hours ago"? A: Yes. Enable the relativeTime plugin and call dayjs().from(otherDate) or dayjs().fromNow().

Q: How do I use Day.js with TypeScript? A: Types ship with the package. Import dayjs and plugins normally. Plugin type augmentation is automatic.

Sources

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