Day.js: A 2kB Moment.js Replacement That Keeps the API You Already Know
⏰ Day.js 2kB immutable date-time library alternative to Moment.js with the same modern API
At a glance
- What is it?
- Day.js is a minimalist, immutable date-time library that mimics Moment.js's API in about 2kB. This review covers its parsing, manipulation, i18n, plugins, and the trade-offs you should check before adopting it.
- Who is it for?
- Adopt Day.js if you need a lightweight, immutable date library with a familiar Moment.js API and you are willing to rely on plugins for advanced formatting and timezone support. Skip it if you require full timezone data or a built-in calendar system without extra dependencies.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 9 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- iamkun/dayjs48,648 ★ · -18
| Repository | 2026-08-18 | 2026-11-15 |
|---|---|---|
| iamkun/dayjs | 48.7k | 48.6k |
-18 Stars in the last 89 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What Day.js Solves and Who It Targets
Day.js addresses the problem of date-time handling in JavaScript with a library that is both small and familiar. The README positions it as a fast 2kB alternative to Moment.js with the same modern API. That pitch targets developers who already use Moment.js and want to reduce bundle size without learning a new API. The core library parses, validates, manipulates, and displays dates and times, which covers the common needs of web applications: formatting user-facing dates, calculating offsets, and comparing timestamps. The intended audience is front-end developers, particularly those working on performance-sensitive sites where every kilobyte matters. The README emphasizes that if you know Moment.js, you already know Day.js, which lowers the learning curve for teams migrating.
The Core Mechanism: Immutable Chaining and Moment.js Compatibility
Day.js works by providing a chainable API that returns new instances rather than mutating the original. The README's example shows this in action: dayjs().startOf('month').add(1, 'day').set('year', 2018).format('YYYY-MM-DD HH:mm:ss'). Each method call returns a new Day.js object, so the original date remains unchanged. This immutability is a deliberate design choice, as the README lists it as a feature under the bullet points. The API mirrors Moment.js's methods: parse with dayjs('2018-08-08'), manipulate with add and set, query with isBefore, and display with format. The underlying data flow is straightforward: you create a Day.js instance from a string, number, or another instance, then chain operations that each produce a fresh instance. This approach avoids the common bug of accidentally mutating a shared date object, which is a real advantage in complex state management.
Getting It Running: Installation and Basic Usage
Installation is a single npm command, as shown in the README: npm install dayjs --save. After that, you import and use it directly. The README gives these examples: dayjs('2018-08-08') to parse, dayjs().format('{YYYY} MM-DDTHH:mm:ss SSS [Z] A') to display, dayjs().set('month', 3).month() to get and set, and dayjs().add(1, 'year') to manipulate. The README's format example mixes tokens with literal characters, such as the braces around {YYYY} and the bracketed [Z]; check the docs on day.js.org for the full token list. The README also shows how to use locales: import 'dayjs/locale/es' and then dayjs.locale('es') for global use, or dayjs('2018-05-05').locale('zh-cn').format() for a single instance. This on-demand loading is a core part of keeping the bundle small, as no locale is included unless you import it.
Internationalization and Plugins: On-Demand Extensions
Day.js handles internationalization through separate locale files that you import only when needed. The README states that none of the locales are included in your build unless you use them, which is a key size-saving measure. You can set a global locale with dayjs.locale('es') or a per-instance locale with .locale('zh-cn'). For advanced features, Day.js uses a plugin system. The README shows how to load the advancedFormat plugin: import advancedFormat from 'dayjs/plugin/advancedFormat', then dayjs.extend(advancedFormat), which enables formats like 'Q Do k kk X x'. This modularity means the core stays tiny, but you must know which plugins you need and import them explicitly. The trade-off is that you trade a single large library for a core plus a set of optional modules, which can complicate dependency management if you use many plugins.
Limitations and When It Is the Wrong Tool
The most obvious limitation is that the core library is minimal. Advanced formatting such as 'Q Do k kk X x' needs the advancedFormat plugin. The repository also carries a timezone plugin test, so timezone support is a plugin concern too; check the Plugin List on day.js.org. Another limitation is that the API, while similar to Moment.js, is not identical. The README says the API is largely Moment.js-compatible rather than identical. If you are migrating from Moment.js, you will need to audit your format strings and method calls to ensure compatibility. For very complex date calculations, such as recurring events or calendar arithmetic, Day.js may be too simplistic. In those cases, a full-featured library like Luxon or date-fns might be a better fit.
A Real Alternative: date-fns and Its Different Approach
A common alternative to Day.js is date-fns, which takes a function-based approach rather than a chainable object API. While Day.js mimics Moment.js's object-oriented style with methods like .add(1, 'day'), date-fns provides standalone functions such as addDays(date, 1). This difference is significant: date-fns encourages a more functional style where you pass a date and get a new date back, which can be more tree-shakeable since you import only the functions you use. In contrast, Day.js's chainable API is convenient for chaining multiple operations but requires the core object to be present. Both libraries are immutable and small, but the mental model differs. If you prefer a functional approach and are not tied to Moment.js syntax, date-fns might be easier to integrate into existing codebases that use functional utilities. For teams coming from Moment.js, Day.js offers a smoother migration path because the API is intentionally similar.
Maintenance, License, and Upgrade Considerations
The repository shows active maintenance with recent releases including v1.11.23 from August 2026, and the project is not archived. The license is MIT, which permits commercial use, modification, and distribution with attribution, but this is not legal advice. The README includes a contributors section and mentions sponsorship, indicating a community-driven project. For upgrade cost, the version history suggests frequent patch releases, which is a sign of ongoing bug fixes. However, the need to manage plugins and locales separately means that an upgrade might require updating multiple packages, and you should check the changelog for any breaking changes in plugin APIs. The default branch is 'dev', which might mean that stable releases are tagged separately, so you should pin your version to a specific release rather than tracking the dev branch. The documentation is extensive, with links to installation and API guides, which helps when upgrading.
Editorial conclusion
Adopt Day.js if you need a lightweight, immutable date library with a familiar Moment.js API and you are willing to rely on plugins for advanced formatting and timezone support. Skip it if you require full timezone data or a built-in calendar system without extra dependencies. Before committing, verify that the specific plugins you need (like advancedFormat, utc, or timezone) are maintained and that your build tooling handles the on-demand imports correctly, as the core library alone covers only basic operations.
Frequently asked questions
Is DayJS better than Moment?
Day.js presents itself as a 2kB alternative to Moment.js with a largely Moment.js-compatible API, MIT licensed, last pushed on 2026-09-15, with releases v1.11.23, v1.11.22 and v1.11.21. It stops at largely compatible, and the plugin list, not the core, is where the rest of the Moment surface has to be looked for.
How do I install dayjs?
The installation line is `npm install dayjs --save`. An Installation Guide lives on day.js.org, and locales and plugins are added afterwards as separate imports rather than as part of that install.
How do I install dayjs plugins?
Import the plugin module and pass it to dayjs.extend: `import advancedFormat from 'dayjs/plugin/advancedFormat'` and then `dayjs.extend(advancedFormat)`. The order matters, since tokens such as those in `Q Do k kk X x` are only handled once the extend call has run.
What is dayjs?
A minimalist JavaScript library that parses, validates, manipulates and displays dates and times for modern browsers, MIT licensed, published from the iamkun/dayjs repository with a dev default branch and documentation on day.js.org.
How do I use dayjs day to day?
Five lines cover the core surface: `dayjs('2018-08-08')` to parse, `dayjs().format('{YYYY} MM-DDTHH:mm:ss SSS [Z] A')` to display, `dayjs().set('month', 3).month()` to get and set, `dayjs().add(1, 'year')` to manipulate and `dayjs().isBefore(dayjs())` to query. Instances are immutable, so you keep what those calls return.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/iamkun-dayjs)Star history chart for your README
[](https://hysenlabs.com/projects/iamkun-dayjs)Was this useful?