Day.js: A 2kB Alternative to Moment.js
/dayjs
Day.js earns its own comparison to Moment.js: the API carries over almost one-to-one, and the 2kB size is the real reason to switch. The README calls it 'largely' compatible, not identical, so migration still means checking edge cases rather than a blind find-and-replace. For a fresh project, it's the easy call.
What is Day.js?
Day.js is a JavaScript library that parses, validates, manipulates, and formats dates, packaged at 2kB with an API that's largely compatible with Moment.js. Every operation returns a new instance rather than mutating the original, and extras like advanced formatting load as opt-in plugins via dayjs.extend().
Key features that make Day.js stand out
- ✓Immutable by design: methods like .add() or .startOf() return a new Day.js instance instead of changing the original.
- ✓Chainable calls read left to right, e.g. dayjs().startOf('month').add(1, 'day').format('YYYY-MM-DD HH:mm:ss').
- ✓2kB core.
- ✓Locale files load on demand — import 'dayjs/locale/es' then dayjs.locale('es') instead of shipping every language by default.
- ✓Plugin system for extras like advancedFormat, added only when you call dayjs.extend().
- ✓API surface close enough to Moment.js that parse, format, get/set, manipulate, and query patterns mostly transfer.
Installing Day.js in your project
Installing Day.js is one command: npm install dayjs --save — that's the only install path shown in the README, with no yarn or pnpm equivalent documented. After that, import dayjs from 'dayjs' and start calling it; the README links out to day.js.org for the full installation guide and API reference instead of documenting every option inline. No separate build step or config file is mentioned.
Parsing, formatting, and manipulating dates
Day.js usage follows the five verbs its own docs use: parse, display, get & set, manipulate, and query. dayjs('2018-08-08') parses a string into an instance. dayjs().format('{YYYY} MM-DDTHH:mm:ss SSS [Z] A') formats it back out with custom tokens. dayjs().set('month', 3).month() gets and sets a unit in the same call. dayjs().add(1, 'year') manipulates by returning a new instance a year later. dayjs().isBefore(dayjs()) queries one instance against another. Chaining these together is how the README's own example works: dayjs().startOf('month').add(1, 'day').set('year', 2018).format('YYYY-MM-DD HH:mm:ss').
Common use cases for Day.js
- •Formatting and displaying dates in a UI without pulling in a large date dependency.
- •Swapping out Moment.js in an existing project mainly to shrink bundle size.
- •Building date pipelines that chain parse, manipulate, and query steps, like dayjs().startOf('month').add(1,'day').
- •Apps that need multiple locales — load only the locale files you use with dayjs.locale().
- •Projects that want to add formatting features later without bloating the base bundle, via the plugin system.
Strengths
- ✓Immutable API removes an entire class of shared-state date bugs that Moment.js's mutable instances allow.
- ✓2kB footprint, with extra functionality added only through plugins you opt into.
- ✓API names and chaining patterns carry over from Moment.js almost directly, so migration is mostly familiar syntax rather than a new library to learn.
- ✓MIT licensed — free to use commercially with no licensing question to resolve.
- ✓I18n support loads per-locale on demand instead of bundling every language by default.
Known limitations of Day.js
- △'Largely Moment.js-compatible' per the README is not 'identical' — a straight find-and-replace migration can still hit method or formatting differences that need manual checking.
- △Core install doesn't include every feature; formatting extras like the advancedFormat plugin have to be found and added individually via dayjs.extend(), which is extra setup work Moment.js users may not expect.
- △The README doesn't document a browser version matrix — 'all browsers supported' is stated without specifics, so teams targeting older environments should verify support themselves.
How Day.js compares to Moment.js and date-fns
Who should use Day.js
Teams already comfortable with Moment.js's API who want the same mental model in a smaller package are the clearest fit for Day.js. It also suits any new project where bundle size matters and you don't need Moment's exact feature set out of the box — you add plugins as you go instead of carrying all of it by default. Projects needing many locales at once should check whether loading each one via dayjs.locale() fits their build pipeline before committing.
Frequently asked questions about Day.js
Day.js is not a strict drop-in — the project describes itself as 'largely' Moment.js-compatible, not identical. Most method names and chaining patterns carry over directly, but Day.js is immutable while Moment.js is not, so code relying on Moment's in-place mutation needs adjusting during migration.
Day.js's own description puts it at 2kB, positioned specifically as a lighter alternative to Moment.js. The README doesn't give Moment.js's exact size for a direct number-to-number comparison, but the 2kB figure is central to why teams pick Day.js over it.
Day.js supports immutable date operations by design — methods like .add() or .startOf() return a new Day.js instance instead of modifying the original one. This is listed among Day.js's core features, and it's one of the main differences from Moment.js, whose methods mutate the instance in place.
Timezone support isn't in Day.js's core feature list — that list covers the Moment.js-style API, immutability, chaining, i18n, small size, and browser support. Day.js ships extra capability through opt-in plugins (the same pattern used for the advancedFormat plugin), so timezone handling is best treated as something you add via a plugin rather than assume is built in.
Day.js is licensed under the MIT License, a permissive open-source license that's free to use in commercial projects. The README states this directly, and MIT doesn't require you to open-source your own code or pay anything to ship Day.js inside a commercial product.
The problem it solves
Moment.js mutates in place — call .add() on an instance and that same object changes, which causes bugs when the instance is shared or reused elsewhere in the code. Day.js's problem statement is narrow: keep the Moment.js method names and mental model intact so migrating doesn't mean relearning an API, but make every operation return a new instance and shrink the whole thing down to 2kB.
Related repositories
Is dayjs worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of dayjs.