Day.js

Day.js is a minimalist JavaScript library that parses, validates, manipulates, and displays dates and times for modern browsers. It was built as a drop-in-style replacement for Moment.js: it mirrors Moment’s chainable, immutable API almost method-for-method, so teams migrating away from Moment’s larger bundle size can often swap the import and keep most of their code working unchanged.

The entire core ships at roughly 2KB minified and gzipped, achieved by keeping the base class deliberately small and pushing everything non-essential — timezone support, relative time, custom parsing, ISO week calculations, and more — into an opt-in plugin system. Locale data for 140+ languages is similarly loaded on demand rather than bundled by default, so applications only pay for the date functionality and languages they actually use.

What You Get

• A ~2KB core (dayjs.min.js) covering parsing, formatting, comparison, and arithmetic — small enough to have negligible impact on bundle size
• A near-drop-in replacement for Moment.js’s API surface, easing migration from Moment-based codebases
• 37 official plugins (timezone, relativeTime, customParseFormat, duration, isoWeek, advancedFormat, and more) that are opt-in via dayjs.extend() so unused functionality never ships to the client
• Built-in internationalization with 140+ locale files, loadable individually
• Full TypeScript type definitions maintained alongside the library
• An immutable API — every date-producing method returns a new Dayjs instance instead of mutating the original

Common Use Cases

• Formatting and displaying dates/times in a specific locale and format string in a web UI
• Computing relative time strings (“3 hours ago”, “in 2 days”) via the relativeTime plugin
• Converting and comparing dates across timezones with the timezone plugin (built on Intl)
• Parsing user-supplied or API date strings with custom formats via customParseFormat
• Date arithmetic in scheduling, booking, or analytics features (add/subtract days, weeks, months) without mutating shared date state
• Replacing an existing Moment.js dependency to cut bundle size with minimal code changes

Under The Hood

Architecture Day.js centers on a single Dayjs class (src/index.js) that stores a native Date internally as $d, alongside cached primitives ($y, $M, $D, $H, $m, $s, $ms, $W) computed once in init() for fast repeated access. All value-changing methods (set, add, startOf, endOf) route through clone()/$set() and return a fresh instance, giving the library its immutability guarantee without a persistent-data-structure library underneath — it simply re-wraps a new native Date each time. The plugin system is the architectural centerpiece: dayjs.extend(plugin) calls each plugin once with (option, Dayjs, dayjs), letting plugins monkey-patch the prototype or the factory function directly. This is what keeps the core at 2KB — anything not universally needed (timezone math, ISO week numbers, relative time, custom parsing) lives in src/plugin/* and is opt-in.

Tech Stack The library has zero runtime dependencies — it only wraps the native Date, Intl, and RegExp APIs. The build pipeline uses Babel for transpilation and Rollup for bundling (see build/), with size-limit enforcing the 2.99KB budget in CI on every change to dayjs.min.js. TypeScript type definitions in types/ are hand-maintained rather than generated. Locale files under src/locale/ (143 of them) are independent modules following a common shape (month/weekday names, ordinal function, formats), so a consumer only pays for the locales they explicitly import.

Code Quality The project enforces 100% line coverage via Jest (coverageThreshold: { global: { lines: 100 } } in package.json), and the test suite runs across multiple timezones (TZ=Pacific/Auckland, TZ=Europe/London, TZ=America/Whitehorse) to catch timezone-dependent bugs before release — a detail that matters heavily for a date library. ESLint is configured with eslint-config-airbnb-base and runs as a pre-commit hook. The trade-off for the aggressive size budget is readability: internal state uses single/double-character property names ($y, $M, $D, $W) and terse helper methods (Utils.p, Utils.w, Utils.s) that prioritize minified output size over self-documenting code — acceptable for a stable, plugin-extensible core but a steeper read for first-time contributors than a more verbosely-named codebase.

API Design The public API is deliberately close to Moment.js’s (dayjs().format('YYYY-MM-DD'), .add(1, 'day'), .isBefore(other)), which minimizes the learning curve for the large existing population of Moment users and keeps method names predictable for newcomers. Getting started requires a single import and no configuration. The plugin activation pattern (dayjs.extend(plugin)) is consistent across all 37 plugins, and TypeScript definitions are automatically compatible with plugin-added methods when the corresponding .d.ts augmentation is imported. The one point of friction is discoverability: since most functionality lives behind opt-in plugins, users unfamiliar with the library often need to consult the docs to find out a needed feature (e.g. timezone conversion) isn’t in the core and requires an explicit dayjs.extend() call first.