Introducing Tempo • A new date library for JavaScript (and TypeScript).

TLDR; Checkout the Tempo docs.

Working with dates and time is one of JavaScript’s weakest points. The native Date object is, under the hood, just a unix timestamp with some utility methods.

Fortunately, there is no shortage of libraries like moment.js, luxon, date-fns, and day.js to fill the gap. Which brings up the question you’ve already asked yourself, — why another date library?

Of course I (👋 its me, Justin Schroeder) didn’t set out to create a whole new library, but the following needs have pushed me over the edge.

Intl.DateTimeFormat styles

The Intl.DateTimeFormat API is an incredible underutilized resource. For example, while it is excellent at formatting dates with locale aware format strings like { dateStyle: "full" } there is no easy way to reverse this process. Friday, March 14, 1997 is the "full" dateStyle in the locale en-US but how do you parse it back into a date? With tempo you can:

import { parse } from '@formkit/tempo'

parse('Friday, March 14, 1997', 'full', 'en')

Parse what you format

Anything you can format with Tempo you can parse with Tempo. For many libraries this is not the case. Bi-directional support allows you to build great locale aware user experiences like the datepicker in FormKit.

Timezones out of the box

Working with dates in real-world applications requires timezone support. Tempo does not require a plugin or additional package but instead mines the Intl.DateTimeFormat for you. Need to know what the time difference between Amsterdam and Kolkata is in 2 months?

import { offset, addMonth } from '@formkit/tempo'

const inTwoMonths = addMonth(new Date(), 2)
offset(inTwoMonths, 'Europe/Amsterdam', 'Asia/Kolkata')

Death to the builder pattern

In almost all cases we should().not().use().theBuilder().pattern(). The builder pattern cannot be tree shaken and offers no substantial benefits over a more functional style (this is not a rebuke of objects, just this pattern). Unfortunately tools like Luxon and DayJS make heavy use of the builder pattern.

Stop the plugins

Many of my favorite date libraries promise an itty bitty core with optional plugins to expand the scope of functionality — unfortunately that little core often doesn’t do much. The same benefit is available to anyone using function notation while tree shaking ensures your project is never bigger than it needs to be. In real-world use cases Tempo is generally ~3-5kb min/gzip including robust support, but depending on what you import it can be as small as 80 bytes.

Better docs

Most of our time interacting with date libraries is reading docs. I want to enjoy that experience. I also want to tinker with things like the format function directly on the page. Tempo’s docs are (I think) great and every example is interactive so you can test your use case before you write a line of code locally.

Why not?

Seriously though, this is an open source project and a free gift to the world. If you are perfectly happy with your current solution, keep using it. If you’d like to try something new — give Tempo a shot.

Highlights

Tempo is full featured in ways you would expect, with full support for day.js style formatting tokens, date parsing, and date manipulation. However it does have some nifty tricks up its sleeves that are worth pointing out:

Convert a dateStyle to tokens

Tempo allows you to extract the formatting tokens of any dateStyle or timeStyle:

import { formatStr } from '@formkit/tempo'

formatStr({ date: 'full', time: 'full' }, 'en')
// dddd, MMMM D, YYYY at h:mm:ss A Z

Using this technique you can create incredible user experiences where users are presented editable dates in their own locale. For examples, checkout FormKit’s datepicker where we use this exact feature: https://formkit.com/inputs/datepicker

Tip: For even more detail you can use the parts() function.

Using timezones

Tempo ships with first class support for timezones — it’s even baked into the format() function.

import { format } from "@formkit/tempo"

// What time is it in LA?
format({
  date: new Date(),
  format: 'hh:mm a',
  tz: 'America/Los_Angeles'
})

You can also easily determine the timezone offset from the user’s location to a fixed place. This is useful when building apps where time at a target location matters. For example booking a rental or a meeting in at a given location from another timezone.

import { tzDate } from '@formkit/tempo'

// Create the date for 1:44pm in Dubai.
tzDate('2025-02-28 13:44', 'Asia/Dubai')

Token ranges

Tempo can "mine" information from Intl.DateTimeFormat. For example, if you want to create a select list of months and display them to a user in their own locale, how can you get all those strings?

import { range } from '@formkit/tempo'

const monthNames = range('MMMM')
// January, February, March...
// or in french:
// janvier,février,mars..

Get building

There are many more features to explore in Tempo — give the docs a quick scan so you know what’s available the next time you’re working on a project that requires working with dates.

While I have you here — can I ask you a personal favor? Consider giving Tempo a star on GitHub...it makes me happy.

If you really like Tempo, consider sponsoring FormKit! We don’t make a dime off this open source work, so any sponsorships we get are hugely encouraging.

❤️

See announcement tweet 👇