Day.js — Lightweight 2kB Date-Time Library for Modern JavaScript

Introduction

Day.js is a minimalist JavaScript date library that parses, validates, manipulates, and displays dates and times. It was created as a lightweight alternative to Moment.js, offering the same familiar API in a package roughly 60 times smaller. The library is immutable by design, preventing accidental mutation bugs common in date handling code.

What Day.js Does

• Parses, validates, and formats dates with a chainable API
• Provides locale-aware formatting for 100+ languages
• Supports relative time display (e.g., "3 hours ago")
• Handles timezone conversion and UTC offsets via plugins
• Offers duration, calendar, and advanced formatting through an extensible plugin system

Architecture Overview

Day.js wraps native JavaScript Date objects in a lightweight immutable wrapper. The core library handles parsing, formatting, and basic manipulation, while all advanced features ship as tree-shakeable plugins. Each operation returns a new Day.js instance rather than mutating the original, making it safe for use in React state and Redux stores.

Self-Hosting & Configuration

• Install via npm, yarn, or pnpm; also available as a CDN script
• Import only the plugins you need to keep bundle size minimal
• Load locale files for internationalization support
• Works in Node.js, browsers, and serverless environments
• Compatible with ES modules and CommonJS

Key Features

• Only 2kB minified and gzipped — ideal for performance-critical apps
• API compatible with Moment.js, easing migration
• Immutable operations prevent subtle date mutation bugs
• Plugin architecture keeps the core small while enabling advanced features
• Full TypeScript support with built-in type definitions

Comparison with Similar Tools

• Moment.js — feature-complete but 67kB and mutable; now in maintenance mode
• date-fns — functional approach with tree-shaking, but larger API surface
• Luxon — built by Moment maintainers with Intl API focus; heavier bundle
• Temporal (TC39) — upcoming native standard; not yet widely available

FAQ

Q: Can I migrate from Moment.js to Day.js easily? A: Yes. Day.js was designed to be a drop-in replacement. Most Moment.js code works with minimal changes.

Q: Does Day.js handle timezones? A: The core library works with local and UTC time. For full IANA timezone support, use the dayjs/plugin/timezone plugin.

Q: Is Day.js suitable for server-side use? A: Absolutely. It runs in Node.js and has no browser-specific dependencies.

Q: How does the plugin system work? A: Plugins are loaded with dayjs.extend(plugin). Each plugin adds methods or formatting tokens to the Day.js prototype without bloating the core.

Sources

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