Never write your own date parsing library.
Never. No exceptions.
Never have I ever…
So… I’ve written my own date parsing library.
Why? Our story begins seven years ago in the year 2018. I made the very sensible choice to adopt luxon as the Date Parsing library for Eleventy. This parsing behavior is used when Eleventy finds a String for the date value in the Data Cascade (though YAML front matter will bypass this behavior when encountering a YAML-compatible date).
This choice was good for Eleventy’s Node.js-only requirements at the time: accurate and not too big (relatively speaking). Eleventy has used luxon since @0.2.12 and has grown with the dependency all the way through @3.7.1 . Now that’s what I call a high quality dependency!
As we move Eleventy to run in more JavaScript environments and runtimes (including on the client) we’ve had to take a hard look at our use of Luxon, currently our largest dependency:
4.7 MB of 21.3 MB (22%) of @11ty/eleventy node_modules
node_modules 229 kB of 806 kB (28%) of @11ty/client (not yet released!) bundle size (unminified)
Given that our use of Luxon is strictly limited to the DateTime.fromISO function for ISO 8601 date parsing (not formatting or display), it would have been nice to enable tree-shaking on the Luxon library to reduce its size in the bundle (though that wouldn’t have helped the node_modules size, I might have settled for that trade-off). Unfortunately, Luxon does not yet support tree-shaking so it’s an all or nothing for the bundle.
The Search Begins
I did the next sensible thing and looked at a few alternatives:
Package Type Disk Size Bundle Size [email protected] Dual 4.59 MB 81.6 kB (min) [email protected] CJS 4.35 MB 294.9 kB (min) [email protected] CJS 670 kB 6.9 kB (min) [email protected] Dual 22.6 MB 77.2 kB (min)
The next in line to the throne was clearly dayjs , which is small on disk and in bundle size. Unfortunately I found it to be inaccurate: dayjs fails about 80 of the 228 tests in the test suite I’m using moving forward.
As an aside, this search has made me tempted to ask: do we need to keep Dual publishing packages? I prefer ESM over CJS but maybe just pick one?
Breaking Changes
Most date parsing woes (in my opinion) come from ambiguity: from supporting too many formats or attempting maximum flexibility in parsing. And guess what: ISO 8601 is a big ’ol standard with a lot of subformats. There is a maintenance freedom and simplicity in strict parsing requirements (don’t let XHTML hear me say that).
Consider "200" . Is this the year 200? Is this the 200th day of the current year? Surprise, in ISO 8601 it’s neither — it’s a decade, spanning from the year 2000 to the year 2010. And "20" is the century from the year 2000 to the year 2100.
Moving forward, we’re tightening up the default date parsing in Eleventy (this is configurable — keep using Luxon if you want!).
Luckily we have a north star date format: RFC 9557, billed as “an extension to the ISO 8601 / RFC 3339” formats and already in use by the upcoming Temporal web standard APIs for date and time parsing coming to a JavaScript runtime near you.
There are a few notable differences:
Format ISO 8601 Date.parse * luxon RFC 9557 YYYY Supported Supported Supported Unsupported YYYY-MM Supported Supported Supported Unsupported YYYY-MM-DD Supported Supported Supported Supported ±YYYYYY-MM-DD Unsupported Supported Supported Supported Optional - delimiters in dates Supported Unsupported Supported Supported YYYY-MM-DDTHH Supported Unsupported Supported Supported YYYY-MM-DD HH (space delimiter) Unsupported Supported Unsupported Supported YYYY-MM-DDtHH (lowercase delimiter) Unsupported Supported Face looking surprised Supported Face looking surprised Supported YYYY-MM-DDTHH:II Supported Unsupported Supported Supported YYYY-MM-DDTHH:II:SS Supported Unsupported Supported Supported Optional : delimiters in time Supported Unsupported Supported Supported YYYY-MM-DDTHH:II:SS.SSS Supported Supported Face looking surprised Supported Supported YYYY-MM-DDTHH:II:SS,SSS Supported Unsupported Supported Supported Microseconds (6 digit precision) Supported Unsupported Supported Supported Nanoseconds (9 digit precision) Supported Unsupported Supported Supported YYYY-MM-DDTHH.H Fractional hours Supported Unsupported Unsupported Unsupported YYYY-MM-DDTHH:II.I Fractional minutes Supported Unsupported Unsupported Unsupported YYYY-W01 ISO Week Date Supported Unsupported Supported Unsupported YYYY-DDD Year Day Supported Unsupported Supported Unsupported HH:II Supported Unsupported Supported Unsupported YYYY-MM-DDTHH:II:SSZ Supported Unsupported Supported Supported YYYY-MM-DDTHH:II:SS±00 Supported Unsupported Supported Supported YYYY-MM-DDTHH:II:SS±00:00 Supported Unsupported Supported Supported YYYY-MM-DDTHH:II:SS±0000 Unsupported Face looking surprised Unsupported Supported Supported
Unsupported Inaccurate parsing Face looking surprised Surprising (to me)
* Note that Date.parse results may be browser/runtime dependent. The results above were generated from Node.js.
A new challenger appears
It is with a little trepidation that I have shipped @11ty/parse-date-strings , a new RFC 9557 compatible date parsing library that Eleventy will use moving forward.
The support table of this library matches the RFC 9557 column documented above. It’s focused on parsing only and our full test suite compares outputs with both the upcoming Temporal API and existing Luxon output.
While there are a few breaking changes when compared with Luxon output (noted above), this swap will ultimately prepare us for native Temporal support without breaking changes later!
Package Type Disk Size Bundle Size @11ty/[email protected] ESM 6.69 kB 2.3 kB (min)
This library saves ~230 kB in the upcoming @11ty/client bundle. It should also allow @11ty/eleventy node_modules install weight to drop from 21.3 MB to 16.6 MB. (Some folks might remember when @11ty/eleventy@1 weighed in at 155 MB!)
Late Additions
For posterity, here are a few other alternative date libraries / Temporal polyfills that I think are worth mentioning (and might help you in different ways on your own date parsing journey):