TL;DR overview
- The Moment.js JavaScript package—once the go-to library for date handling—has been officially deprecated, with maintainers recommending migration to modern alternatives such as Day.js, date-fns, or Luxon.
- Moment.js carries significant bundle size overhead and its mutable API design introduces subtle bugs; continuing to use it in new projects accumulates technical debt that becomes harder to address over time.
- Migration is a code health investment: modern date libraries are immutable, tree-shakeable, and better aligned with native JavaScript improvements, reducing both bundle size and bug surface.
- Teams should audit their npm dependency graphs for Moment.js usage and prioritize migration in active codebases, particularly where bundle performance or time zone handling is a business concern.
Moment.js is a popular date-handling library that, at one point, was being downloaded nearly 15 million times a week. Despite its popularity, Moment’s open source maintainers announced in September 2020 that they were deprecating the project. Since its creation in 2011, Moment’s essential design hadn’t changed much, despite the rapid development of the JavaScript ecosystem in which it lived. Because so many projects depended on Moment, its maintainers chose to prioritize stability over new features, which could cause breaking changes for millions of projects and would have been “a tremendous undertaking and would make Moment a different library entirely.”
In deprecating the library, Moment’s maintainers declared it a “legacy project in maintenance mode.” That meant the library would continue to exist with limited support and without any new features. Moment’s maintainers discouraged its use in new projects and suggested users consider more modern alternatives. Moment, they said, was no longer the best option for modern applications for a few reasons:
- Moment.js objects are mutable, which can cause hard-to-diagnose problems.
- Moment doesn't work well with modern "tree shaking" algorithms—used to remove dead code—so it tends to increase the size of web application bundles.
- Modern web browsers and other JavaScript implementations have better date support than when Moment was first created, so a modern date-handling library has to do less work.
As developers, we know that continued use of deprecated open source software can lead to problems, or even open back doors for malicious activity. So earlier this year, we removed the use of Moment in our code base.
But Moment has been deprecated for a couple years now. Why did it take us so long?
Like many other applications, ours used Moment extensively to handle dates and times in many places around the application. Removing Moment would require significant changes to large chunks of the codebase. Those changes require testing, both manual and automated, and those sorts of disruptions can be costly.
Before changing anything, we had to find a replacement library. If you’re dealing with a deprecated library, you’d better hope it’s a popular one for which there are already good replacements. We got lucky with Moment. It had been so popular for such a long time that developers had been working on replacements for years. We considered three alternative options, each with its advantages:
- Luxon was started by a member of the Moment community and has a similar object-chaining API as Moment, but with immutable objects rather than mutable ones, which helps prevent subtle bugs.
- Day.js also has a similar API as Moment, and in many instances can be used as a drop-in replacement for Moment.
- date-fns is built with a functional programming approach rather than an object-oriented approach. This allows for a simpler API that conforms more closely with JavaScript’s built-in date-handling API.
While there was extensive use of Moment in the application, the way we used it was quite simple; we used no complicated date transformations with Moment, and none of our code relied on mutated Moment objects. So we chose Day.js as a drop-in replacement for Moment. Once we got organizational buy-in to make the switch, it was time for brute force replacement and testing. There was a bit of tweaking and a few bugs to fix as we adapted to the particulars of the new library. And then, we were done with Moment.
While the Day.js API is nearly identical to the Moment API, there are a couple differences to watch out for if you decide to make the switch:
- Day.js uses a core + plugin system. For certain format strings and features, you will need to register the appropriate plugins.
- Day.js objects are immutable.
Of course, there is no guarantee that Day.js or any other library will not also be deprecated at some point in the future. Whether or not we move to a different library later on, removing Moment helped us reduce bundle sizes by a significant amount, and more importantly, we are no longer relying on deprecated software.
Do you know if all the open source packages in your application’s software supply chain are actively maintained? We can help you find out.