NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm · #361 most downloaded on npm
Modern JavaScript date utility library
Last release 4 months ago
29 May 2026
Ships unpredictably
gaps range from 2 weeks to 1.7 years
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
12 years old
209 releases · first in 2014
v5 focuses on reducing the date-fns package size. Compared to v4.3.0, this version reduces the zipped package size from 5.83 MB down to 2.89 MB .
v5 focuses on reducing the date-fns package size. Compared to v4.3.0, this version reduces the zipped package size from 5.83 MB down to 2.89 MB.
It removes the CDN scripts from the date-fns package and moves them to a separate @date-fns/cdn package.
It is just the first step in optimizing the package size. Expect further size reduction in the future versions.
@date-fns/cdn npm package instead of date-fns. Users relying on the latest CDN version (e.g., https://cdn.jsdelivr.net/npm/date-fns/cdn.min.js) would be served a polyfill that inserts a script with the correct URL (https://cdn.jsdelivr.net/npm/@date-fns/cdn/cdn.min.js) into the page.It allowed reducing the zipped package size from 5.83 MB down to 3.96 MB without introducing any breaking changes.
One column per quarter.
This release revisits the approach to CDN usage and introduces a new package, @date-fns/cdn and deprecates the date-fns CDN scripts. It allowed reducing the zipped package size from 5.83 MB down to 3.96 MB without introducing any breaking changes.
In v5.0.0-alpha.0 where CDN scripts are completely removed from date-fns the change is more significant and brings the zipped package size down to 2.89 MB.
It is just the first step in optimizing the package size. Expect further size reduction in the future v4 and v5 versions.
DEPRECATED: The date-fns CDN scripts are now deprecated and will be removed in the next major release. Please switch to the new @date-fns/cdn package for CDN usage.
Removed CDN source maps to reduce the package size. If you rely on them, please switch to the new @date-fns/cdn package that still includes them.
Kudos to @ImRodry and @puneetdixit200 for their contributions.
Kudos to @ImRodry and @puneetdixit200 for their contributions.
Fixed missing modularized optimization fallback (for Next.js and others). See #4193.
Fixed pt locale first day of week to be Sunday. See #4195 by @ImRodry.
Fixed zh-CN, zh-HK, and zh-TW locale month parsing for October, November, and December. See #4194 by @puneetdixit200.
Kudos to @ImRodry and @puneetdixit200 for their contributions.
Fixed missing modularized optimization fallback (for Next.js and others). See #4193.
Fixed pt locale first day of week to be Sunday. See #4195 by @ImRodry.
Fixed zh-CN, zh-HK, and zh-TW locale month parsing for October, November, and December. See #4194 by @puneetdixit200.
package.json a bit smaller by removing dev fields when building the package.Fixed type definitions missing in v4.2.0 due to TypeScript misconfiguration.
This is a minor release in all senses, it only includes documentation updates (first of many) that points to the new You Don't Need date-fns* page.
This is a minor release in all senses, it only includes documentation updates (first of many) that points to the new You Don't Need date-fns* page.
* Not really
add, addBusinessDays, and addDays.This release adds time zone support to format functions (that I somehow missed when working on the feature) and fixes a few bugs.
This release adds time zone support to format functions (that I somehow missed when working on the feature) and fixes a few bugs.
Make sure also upgrade TZDate to v1.0.2 as it includes a bunch of critical bug fixes.
constructFrom throwing an exception on null arguments. While null isn't allowed, the functions should rather return Invalid Date or NaN in such cases. See #3885.format, formatISO, formatISO9075, formatRelative and formatRFC3339. See #3886.Another great news is that there aren't many breaking changes in this release. All of them are type-related and will affect only those explicitly usin…
I have great news! First, ten years after its release, date-fns finally gets first-class time zone support.
Another great news is that there aren't many breaking changes in this release. All of them are type-related and will affect only those explicitly using internal date-fns types. Finally, it has been less than a year since the last major release, which is an improvement over the previous four years between v2 and v3. I plan on keeping the pace and minimizing breaking changes moving forward.
Read more about the release in the announcement blog post.
Added time zones support via @date-fns/tz's TZDate class and tz helper function. See its README for the details about the API.
All relevant functions now accept the context in option, which allows to specify the time zone to make the calculations in. If the function also returns a date, it will be in the specified time zone:
import { addDays, startOfDay } from "date-fns";
import { tz } from "@date-fns/tz";
startOfDay(addDays(Date.now(), 5, { in: tz("Asia/Singapore") }));
//=> "2024-09-16T00:00:00.000+08:00"In the example, addDays will get the current date and time in Singapore and add 5 days to it. startOfDay will inherit the date type and return the start of the day in Singapore.
The function arguments, as well as Interval's start and end, now can be of different types, allowing you to mix UTCDate, TZDate, Date, and other extensions, as well as primitives (strings and numbers).
The functions will normalize these values, make calculations, and return the result in the same type, preventing any bugs caused by the discrepancy. If passed, the type will be inferred from the context in option or the first encountered argument object type. The Interval's start and end will be considered separately, starting from start.
In the given example, the result will be in the TZDate as the first argument is a number, and the start takes precedence over the end.
clamp(Date.now(), {
start: new TZDate(start, "Asia/Singapore"),
end: new UTCDate(),
});
//=> TZDateBREAKING: This release contains a bunch of types changes that should not affect the library's expected usage. The changes are primarily internal and nuanced, so rather than listing them here, I recommend you run the type checker after the upgrade. If there are unfixable problems, please open an issue.
BREAKING: The package is now ESM-first. CommonJS is still supported, and it should not affect most users, but it might break in certain environments. If you encounter any issues, please report them.
$ by properly wrapping the code in an IIFE.Nothing published for this version
Nothing published for this version
On this release worked @kossnocorp and @world1dan . Also, thanks to @seated for sponsoring me .
On this release worked @kossnocorp and @world1dan. Also, thanks to @seated for sponsoring me.
Kudos to @fturmel , @kossnocorp , @makstyle119 , @tan75 , @marcreichel , @tareknatsheh and @audunru for working on the release. Also, thanks to @seate
Kudos to @fturmel, @kossnocorp, @makstyle119, @tan75, @marcreichel, @tareknatsheh and @audunru for working on the release. Also, thanks to @seated for sponsoring me.
Added the constructNow function that creates the current date using the passed reference date's constructor.
Kudos to @kossnocorp , @sakamossan , and @Revan99 for working on the release. Also, thanks to @seated for sponsoring me.
Kudos to @kossnocorp, @sakamossan, and @Revan99 for working on the release. Also, thanks to @seated for sponsoring me.
Kudos to @kossnocorp and @fturmel for working on the release.
Kudos to @kossnocorp and @fturmel for working on the release.
Fixed DST issue in getOverlappingDaysInIntervals, resulting in an inconsistent number of days returned for intervals starting and ending in different DST periods.
Fixed functions incorrectly using trunc instead of round. The bug was introduced in v3.3.0. The affected functions: differenceInCalendarDays, differenceInCalendarISOWeeks, differenceInCalendarWeeks, getISOWeek, getWeek, and getISOWeeksInYear.
On this release worked @kossnocorp, @TheKvikk, @fturmel and @ckcherry23.
On this release worked @kossnocorp, @TheKvikk, @fturmel and @ckcherry23.
Fixed the bug in getOverlappingDaysInIntervals caused by incorrect sorting of interval components that led to 0 for timestamps of different lengths.
Fixed bugs when working with negative numbers caused by using Math.floor (-1.1 → -2) instead of Math.trunc (-1.1 → -1). Most of the conversion functions (i.e., hoursToMinutes) were affected when passing some negative fractional input. Also, some other functions that could be possibly affected by unfortunate timezone/date combinations were fixed.
The functions that were affected: format, parse, getUnixTime, daysToWeeks, hoursToMilliseconds, hoursToMinutes, hoursToSeconds, milliseconds, minutesToMilliseconds, millisecondsToMinutes, monthsToYears, millisecondsToHours, millisecondsToSeconds, minutesToHours, minutesToSeconds, yearsToQuarters, yearsToMonths, yearsToDays, weeksToDays, secondsToMinutes, secondsToHours, quartersToYears, quartersToMonths and monthsToQuarters.
Fixed the Czech locale's formatDistance to include 1 in formatDistance.
Fixed differenceInSeconds and other functions relying on rounding options that can produce a negative 0.
Added a preprocessor to the locales API, enabling fixing a long-standing bug in the French locale. (#1391)
Added missing yearsToDays to the FP submodule.
Made functions using rounding methods always return 0 instead of -0.
This release is brought to you by @kossnocorp, @fturmel, @grossbart, @MelvinVermeer, and @jcarstairs-scottlogic.
This release is brought to you by @kossnocorp, @fturmel, @grossbart, @MelvinVermeer, and @jcarstairs-scottlogic.
Fixed types compatibility with Lodash's flow and fp-ts's pipe. (#3641)
format, lightFormat, and parse internals that enable 3rd-parties to consume those.This release is brought to you by @kossnocorp, @makstyle119 and @dmgawel.
This release is brought to you by @kossnocorp, @makstyle119 and @dmgawel.
Added a warning about using protected tokens like Y or D without passing a corresponding option. See #2950.
On this release worked @imwh0im, @jamcry and @tyrw.
On this release worked @imwh0im, @jamcry and @tyrw.
This release is brought to you by @goku4199.
This release is brought to you by @goku4199.
This release is brought to you by @kossnocorp.
This release is brought to you by @kossnocorp.
Rolled back pointing ESM types to the same d.ts files. Instead, now it copies the content to avoid the Masquerading as CJS problem reported by "Are th
d.ts files. Instead, now it copies the content to avoid the Masquerading as CJS problem reported by "Are the types wrong?".Fixed yet another issue caused by ESM types by pointing to the same d.ts files.
Fixed yet another issue caused by ESM types by pointing to the same d.ts files.
Added package.json to exports to provide access to tooling.
Fixed TypeScript 5.4 build break by using the latest type names.
Nothing published for this version
Fixed an error in certain environments caused by d.mts files exporting only types.
d.mts files exporting only types.Nothing published for this version
BREAKING: date-fns is now a dual-package with the support of both ESM and CommonJS. The files exports are now explicitly in the package.json. The ESM
BREAKING: date-fns is now a dual-package with the support of both ESM and CommonJS. The files exports are now explicitly in the package.json. The ESM files now have .mjs extension.
BREAKING: The package now has a flat structure, meaning functions are now named node_modules/date-fns/add.mjs, locales are node_modules/date-fns/locale/enUS.mjs, etc.
BREAKING: Now all file content’s exported via named exports instead of export default, which will require change direct imports i.e. const addDays = require(‘date-fns/addDays’) to const { addDays } = require(‘date-fns/addDays’).
BREAKING: TypeScript types are now completely rewritten, check out the d.ts files for more information.
BREAKING: constants now is not exported via the index, so to import one use import { daysInYear } from "date-fns/constants";. It improves compatibility with setups that modularize imports like Next.js.
BREAKING: Functions now don’t check the number of passed arguments, delegating this task to type checkers. The functions are now slimmer because of this.
BREAKING The arguments are not explicitly converted to the target types. Instead, they are passed as is, delegating this task to type checkers.
BREAKING: Functions that accept Interval arguments now do not throw an error if the start is before the end and handle it as a negative interval. If one of the properties in an Invalid Date, these functions also do not throw and handle them as invalid intervals.
areIntervalsOverlapping normalize intervals before comparison, so { start: a, end: b } is practically equivalent to { start: b, end: a }. When comparing intervals with one of the properties being Invalid Date, the function will return false unless the others are valid and equal, given the inclusive option is passed. Otherwise, and when even one of the intervals has both properties invalid, the function will always return false.
getOverlappingDaysInIntervals now normalizes intervals before comparison, so { start: a, end: b } is practically equivalent to { start: b, end: a }. If any of the intervals’ properties is an Invalid Date, the function will always return 0.
isWithinInterval now normalizes intervals before comparison, so { start: a, end: b } is practically equivalent to { start: b, end: a }. If any of the intervals’ properties is an Invalid Date, the function will always return false.
intervalToDuration now returns negative durations for negative intervals. If one or both of the interval properties are invalid, the function will return an empty object.
The eachXOfInterval functions (eachDayOfInterval, eachHourOfInterval, eachMinuteOfInterval, eachMonthOfInterval, eachWeekendOfInterval, eachWeekendOfMonth, eachWeekendOfYear, eachWeekOfInterval, eachYearOfInterval) now return a reversed array if the passed interval’s start is after the end. Invalid properties will result in an empty array. Functions that accept the step option now also allow negative, 0, and NaN values and return reversed results if the step is negative and an empty array otherwise.
BREAKING: intervalToDuration now skips 0 values in the resulting duration, resulting in more compact objects with only relevant properties.
BREAKING: roundToNearestMinutes now returns Invalid Date instead of throwing an error when nearestTo option is less than 1 or more than 30.
BREAKING: IE is no longer supported.
BREAKING: Now all functions use Math.trunc rounding method where rounding is required. The behavior is configurable on a per-function basis.
BREAKING: Undocumented onlyNumeric option was removed from nn and sv locales. If you relied on it, please contact me.
BREAKING: Flow is not supported anymore. If you relied on it, please contact me.
BREAKING: The locales now use regular functions instead of the UTC version, which should not break any code unless you used locales directly.
All functions that accept date arguments now also accept strings.
All functions now export options interfaces.
Now functions allow passing custom Date extensions like UTCDate. They will detect and use the arguments constructor to generate the result of the same class.
eachMonthOfInterval, eachQuarterOfInterval, eachWeekOfInterval, and eachYearOfInterval now accept the step option like most of the eachXOfInterval functions.
A new interval function that validates interval, emulating the v2 interval functions behavior.
differenceInX functions now accept options and allow setting up roundingMethod that configures how the result is rounded. Math.trunc is the default method.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Kudos to @kossnocorp and @Andarist for working on the release.
Kudos to @kossnocorp and @Andarist for working on the release.
This release is prepared by our own @leshakoss.
This release is prepared by our own @leshakoss.
Fixed a breaking change in `intervalToDuration` by removing a recently introduced RangeError.
This release is brought to you by @nopears, @vadimpopa and @leshakoss.
Thanks to @fturmel for working on the release.
Thanks to @fturmel for working on the release.
_Internal_: removed "v2.0.0 breaking changes" section from individual function docs
On this release worked @tan75, @kossnocorp, @nopears, @Balastrong, @cpapazoglou, @dovca, @aliasgar55, @tomchentw, @JuanM04, @alexandresaura, @fturmel, @aezell, @andersravn, @TiagoPortfolio, @SukkaW, @Zebreus, @aviskarkc10, @maic66, @a-korzun, @Mejans, @davidspiess, @alexgul1, @matroskin062, @undecaf, @mprovenc, @jooola and @leshakoss.
Fixed long formatters in the South African English locale (en-ZA).
Fixed weekday format for formatRelative in the Portuguese locale (pt).
Fixed issue parsing months in Croatian (hr), Georgian (ka) and Serbian (sr and sr-Latn) locales.
Kudos to @tan75, @fturmel, @arcanar7, @jeffjose, @helmut-lang, @zrev2220, @jooola, @minitesh, @cowboy-bebug, @mesqueeb, @JuanM04, @zhirzh, @damon02 an
Kudos to @tan75, @fturmel, @arcanar7, @jeffjose, @helmut-lang, @zrev2220, @jooola, @minitesh, @cowboy-bebug, @mesqueeb, @JuanM04, @zhirzh, @damon02 and @leshakoss for working on the release.
Kudos to @tan75, @hg-pyun, @07akioni, @razvanmitre, @Haqverdi, @pgcalixto, @janziemba, @fturmel, @JuanM04, @zhirzh, @seanghay, @bulutfatih, @nodeadtre
Kudos to @tan75, @hg-pyun, @07akioni, @razvanmitre, @Haqverdi, @pgcalixto, @janziemba, @fturmel, @JuanM04, @zhirzh, @seanghay, @bulutfatih, @nodeadtree, @cHaLkdusT, @a-korzun, @fishmandev, @wingclover, @Zacharias3690, @kossnocorp and @leshakoss for working on the release.
Fixed translation for quarters in format in Chinese Simplified locale (zh-CN).
Fixed regular expressions for parse in Estonian locale (er).
Fixed the format of zeros in formatDuration in Czech locale (cs).
Fixed constants not having proper TypeScript and Flow types.
Fixed eachMinuteOfInterval not handling intervals less than a minute correctly.
Thanks to @kossnocorp, @leshakoss, @tan75, @gaplo, @AbdAllahAbdElFattah13, @fturmel, @kentaro84207, @V-Gutierrez, @atefBB, @jhonatanmacazana, @zhirzh,
Thanks to @kossnocorp, @leshakoss, @tan75, @gaplo, @AbdAllahAbdElFattah13, @fturmel, @kentaro84207, @V-Gutierrez, @atefBB, @jhonatanmacazana, @zhirzh, @Haqverdi, @mandaputtra, @micnic and @rikkalo for working on the release.
This release is brought to you by @kossnocorp, @gierschv, @fturmel, @redbmk, @mprovenc, @artyom-ivanov and @tan75.
This release is brought to you by @kossnocorp, @gierschv, @fturmel, @redbmk, @mprovenc, @artyom-ivanov and @tan75.
Kudos to Sasha Koss, Lucas Silva, Jan Ziemba, Anastasia Kobzar, Deepak Gupta, Jonas L, Kentaro Suzuki, Koussay Haj Kacem, fturmel, Tan75 and Adriaan C
Kudos to Sasha Koss, Lucas Silva, Jan Ziemba, Anastasia Kobzar, Deepak Gupta, Jonas L, Kentaro Suzuki, Koussay Haj Kacem, fturmel, Tan75 and Adriaan Callaerts for working on the release.
Used 1 instead of ein for German formatDuration to make it consistent with other locales and formats. (#2505)
Made Norwegian formatDuration consistent with other locales by using numeric representation instead of written. (#2469)
Use the word "sekunda" instead of "vteřina" for second in the Czech locale.
Made Flemish short date format corresponds to the Flemish government.
Thanks to Liam Tait, fturmel, Takuya Uehara, Branislav Lazic, Seyyed Morteza Moosavi, Felipe Armoni, Sasha Koss, Michael Mok, Tan75 and Maxim Topciu f
Thanks to Liam Tait, fturmel, Takuya Uehara, Branislav Lazic, Seyyed Morteza Moosavi, Felipe Armoni, Sasha Koss, Michael Mok, Tan75 and Maxim Topciu for working on the release.
Thanks to Sasha Koss for working on the release.
On this release worked Sasha Koss, Lucas Silva, Lay, jwbth, fturmel, Tan75 and Anastasia Kobzar.
On this release worked Sasha Koss, Lucas Silva, Lay, jwbth, fturmel, Tan75 and Anastasia Kobzar.
daysToWeekshoursToMillisecondshoursToMinuteshoursToSecondsmillisecondsToHoursmillisecondsToMinutesmillisecondsToSecondsminutesToHoursminutesToMillisecondsminutesToSecondsmonthsToQuartersmonthsToYearsquartersToMonthsquartersToYearssecondsToHourssecondsToMillisecondssecondsToMinutesweeksToDaysyearsToMonthsyearsToQuartersThis release is brought to you by Maxim Topciu.
This release is brought to you by Maxim Topciu.
Kudos to Aleksei Korzun, Maxim Topciu, Jonas L, Mohammad ali Ali panah and Tan75 for working on the release.
Kudos to Aleksei Korzun, Maxim Topciu, Jonas L, Mohammad ali Ali panah and Tan75 for working on the release.
Fixed a breaking change introduced by using modern default argument value syntax (see https://github.com/Hacker0x01/react-datepicker/issues/2870).
Thanks to Sasha Koss for working on the release.
This release is brought to you by Aleksei Korzun, Tan75, Rubens Mariuzzo, Christoph Stenglein and Clément Tamisier.
This release is brought to you by Aleksei Korzun, Tan75, Rubens Mariuzzo, Christoph Stenglein and Clément Tamisier.
Kudos to fturmel for working on the release.
Kudos to fturmel for working on the release.
Kudos to Maxim Topciu for working on the release.
Kudos to Maxim Topciu for working on the release.
This release is brought to you by Sasha Koss and Tan75.
This release is brought to you by Sasha Koss and Tan75.
isDate Flow typings that we broke in v2.20.0.This release is brought to you by Sasha Koss, Maxim Topciu, tu4mo, Tan75, Ardit Dine, Carl Rosell, Roman Mahotskyi, Mateusz Krzak, fgottschalk, Anasta
This release is brought to you by Sasha Koss, Maxim Topciu, tu4mo, Tan75, Ardit Dine, Carl Rosell, Roman Mahotskyi, Mateusz Krzak, fgottschalk, Anastasia Kobzar, Bilguun Ochirbat, Lesha Koss, YuLe and guyroberts21.
Made formatDistanceStrict and formatDistanceToNowStrict always return 1 year instead of 12 months. (#2388)
Fixed nextDay, nextMonday and nextTuesday missing in exports and type definitions. (#2325)
Assigned the correct `firstWeekContainsDate` value (`4`) for the French locale.
Thanks to Tan75 and Lesha Koss.
Kudos to @shaykav, @davidgape89, @rikkalo, @tan75, @talgautb, @owenl131, @kylesezhi, @inigoiparragirre, @gius, @Endeauvirr and @frankyston.
Kudos to @shaykav, @davidgape89, @rikkalo, @tan75, @talgautb, @owenl131, @kylesezhi, @inigoiparragirre, @gius, @Endeauvirr and @frankyston.
Fixed differenceInMonths for edge cases, such as the end of February dates.
Fixed formatDuration week translation in pt and pt-BR locales.
Made Japanese locale to use the correct value for the start of the week.
Fixed the short and medium date formats in the Czech locale.
Added intlFormat a lightweight formatting function that uses Intl API. Eventually, it will become the default formatting function, so it's highly recommended for new code.
Added an ability to format lowercase am/pm with aaa and bbb tokens.
Kudos to @aleksaps, @leedriscoll and @BanForFun for pull-requests!
Kudos to @aleksaps, @leedriscoll and @BanForFun for pull-requests!
formatRelative.Kudos to @jvpelt, @piotrl, @yotamofek, @dwaxweiler, @leedriscoll and @bradevans for working on the release. Also thanks to @PascalHonegger, @pickfire,
Kudos to @jvpelt, @piotrl, @yotamofek, @dwaxweiler, @leedriscoll and @bradevans for working on the release. Also thanks to @PascalHonegger, @pickfire, @TheJaredWilcurt, @SidKH and @nfantone for improving the documentation.
1 minute and 2 days.formatRFC3339 formatting timezone offset with minutes.formatDuration.Thanks to @belgamo, @Matsuuu, @Imballinst, @arsnyder16, @pankajupadhyay29, @DCBN, @leedriscoll, @gottsohn, @mukuljainx and @dtriana for working on the
Thanks to @belgamo, @Matsuuu, @Imballinst, @arsnyder16, @pankajupadhyay29, @DCBN, @leedriscoll, @gottsohn, @mukuljainx and @dtriana for working on the release. Also kudos to @KidkArolis, @imgx64, @fjc0k, @wmonk, @djD-REK, @dandv, @psimk and @brimworks for improving the documentation.
addBusinessDays when input date is a weekend day.parseISO not returning Invalid Date on incorrect string when there are spaces in it.es round-tripping dates with Wednesday.d/EEEE ordering in tokens like PPPPP.Kudos to @julamb, @JacobSoderblom, @justingrant, @dragunoff, @jmate0321, @gbhasha, @rasck, @AlbertoPdRF, @sebastianhaberey and @giogonzo for working o
Kudos to @julamb, @JacobSoderblom, @justingrant, @dragunoff, @jmate0321, @gbhasha, @rasck, @AlbertoPdRF, @sebastianhaberey and @giogonzo for working on the release!
add, addDays and addMonths.formatDistance strings in the Hungarian locale.formatLong in the Spanish locale.formatRelative in the Italian locale.Thanks to @JorenVos, @developergouli, @rhlowe and @justingrant for working on the release!
Thanks to @JorenVos, @developergouli, @rhlowe and @justingrant for working on the release!
Kudos to @leshakoss, @skyuplam, @so99ynoodles, @dkozickis, @belgamo, @akgondber, @dcousens and @BoomDev for working on the release!
Kudos to @leshakoss, @skyuplam, @so99ynoodles, @dkozickis, @belgamo, @akgondber, @dcousens and @BoomDev for working on the release!
setDay with weekStartsOn != 0.Your coding agent can read these notes before it upgrades. Set up the MCP server →