date-fns v2 beta is out!

For those who don't know, date-fns is a modern JavaScript date utility library. It's focused on build size and performance. It's tree-shakable so only used functionality will be included in your build. The minimal build size is just 295 B that makes it the smallest date library in JS world! Unlike other date libraries, date-fns uses native Date object and embraces the functional approach.

It took us two years to develop v2, and during the time we reworked every bit of the library. We've merged nearly 500 pull requests from a hundred contributors! Today I invite you to give it a try:

npm install date-fns@next --save
# or using Yarn:
yarn add date-fns@next

It's stable, and we don't plan to change the API. It could have been a final release, but as it introduces plenty of breaking changes in the upcoming days, we're going to work on making the upgrade process as smooth as possible. In meanwhile, you can help us by testing the library and sharing your feedback.

What's new?

Here some most exciting features, for the full list of changes (it's enormous!) see the changelog: https://date-fns.org/v2.0.0-beta.1/docs/Change-Log

EcmaScript Modules. With v2 we ship both ESM and CommonJS, so if your bundler supports tree-shaking you can import functions directly from the root of the package and still get slim build:

import { format, formatDistance, formatRelative, subDays } from 'date-fns'

format(new Date(), "'Today is a' iiii")
//=> "Today is a Wednesday"

formatDistance(subDays(new Date(), 3), new Date())
//=> "3 days ago"

formatRelative(subDays(new Date(), 3), new Date())
//=> "last Friday at 7:26 p.m."

Also, we adopted the camelcase naming scheme:

// Before v2.0.0
import addDays from 'date-fns/add_days'

// v2.0.0 onward
import addDays from 'date-fns/addDays'

Another feature I'm sure FP fans will love is new FP submodule. It introduces copies of regular functions which accept arguments in inverse order and curryied by default. They could be imported from date-fns/fp and used along with regular functions.

The main advantage of FP functions is the support of functional-style function composing.

const { differenceInDays: regularDifferenceInDays } = require('date-fns')
const { differenceInDays: fpDifferenceInDays } = require('date-fns/fp')

regularDifferenceInDays(Date.now(), 0)
//=> 17815

fpDifferenceInDays(0, Date.now())
//=> 17815

fpDifferenceInDays(0)(Date.now())
//=> 17815

const daysSinceUnixEpoch = fpDifferenceInDays(0)
daysSinceUnixEpoch(Date.now())
//=> 17815

We added dozens of new functions, but one requires special attention: parse. It allows parsing a string using arbitrary format:

import { parse } from 'date-fns'

parse('02/11/2014', 'MM/dd/yyyy', new Date())
//=> Tue Feb 11 2014 00:00:00

That was possibly the most requested feature and to make it happen we completely rewrote I18n code.

Also, we carefully refined every function to make date-fns consistent, predictable, and reliable. We made it work in edge cases like ECMAScript would work. You can read more about v2 API design in a DEV post.

What's next?

After we ship the final version, there are few initiatives that we want to focus on:

• UTC versions of functions.
• Durations support.
• Time zones (right now TZ functionality is provided by date-fns-tz).
• Integration with Intl API.

Acknowledgments

Neither v2 nor date-fns, in general, would not be possible without 153 contributors that helped to make date-fns awesome. I wish I could mention everyone but the list would be too big. But I can't skip my brother, Lesha Koss that wrote the bulk of date-fns code. You're amazing!

Thank you for reading! I hope you'll love v2. Join date-fns community at Spectrum and follow us on Twitter.