Skip to main content

Date Plugins

Date plugins allow you to format dates, get unix timestamps, or manipulate dates by adding or removing hours, days, weeks, and more.

The date plugins depend on date-fns, and you will need to install it separately from microfern.

npm i @microfern/date

You can then import and use the plugins when calling format.

import { format } from "microfern";
import { DATE_PLUGINS } from "@microfern/date";

// I'll eat another apple on 1719761084
format(
  "I'll eat another apple on {{ date | toUnixTimestamp }}",
  { now: new Date().toString() },
  { plugins: DATE_PLUGINS }
  // If you want to use both the date plugins and the built-in plugins, you can merge them like this:
  // { plugins: { ...DATE_PLUGINS, ...BUILT_IN_PLUGINS } }
);

Date Inputs​

The date plugins can accept dates formatted in multiple ways:

  • a Unix timestamp (number formatted as a string), e.g. "1719761084"
  • an ISO 8601 formatted date-time string, e.g. "2023-05-31T09:00:00-05:00"
  • a Date object formatted with .toString() e.g. "Sun Jun 30 2024 12:39:20 GMT-0500 (Central Daylight Time)"

List of Date Plugins​

toUnixTimestamp​

This plugin converts a date string to a Unix timestamp (seconds since January 1, 1970).

Template
The avocado will be ripe at timestamp {{ ripeness | toUnixTimestamp }}
Variables
{
    "ripeness": "2023-06-15T14:30:00Z"
}
Output
The avocado will be ripe at timestamp 1686839400
Edit the template or variables to see the output change.

toISODateTime​

This plugin converts a date string to an ISO 8601 formatted date-time string.

Template
The great cucumber harvest of {{ harvest | toISODateTime }}
Variables
{
    "harvest": "1685541600"
}
Output
The great cucumber harvest of 2023-05-31T14:00:00Z
Edit the template or variables to see the output change.

addTime​

This higher-order plugin adds a specified amount of time to a date. It requires two parameters: the amount and the unit of time.

Template
Your artichoke hearts will be ready in {{ cookTime | addTime 30 minutes }}
Variables
{
    "cookTime": "2023-06-15T12:00:00Z"
}
Output
Your artichoke hearts will be ready in 2023-06-15T12:30:00Z
Edit the template or variables to see the output change.

subtractTime​

This higher-order plugin subtracts a specified amount of time from a date. It requires two parameters: the amount and the unit of time.

Template
The last thyme I saw you was {{ lastMeeting | subtractTime 2 days }}
Variables
{
    "lastMeeting": "2023-06-15T09:00:00Z"
}
Output
The last thyme I saw you was 2023-06-13T09:00:00Z
Edit the template or variables to see the output change.

formatDateTime​

This higher-order plugin formats a date according to the specified format string. It can take multiple format tokens as separate arguments.

Template
The Annual Turnip Toss will be held on {{ event | formatDateTime MMMM do 'at' h:mm a }}
Variables
{
    "event": "2023-07-01T14:30:00Z"
}
Output
The Annual Turnip Toss will be held on July 1st at 2:30 PM
Edit the template or variables to see the output change.

Time Units​

When using addTime and subtractTime, you can specify the following time units:

  • years
  • months
  • weeks
  • days
  • hours
  • minutes
  • seconds

Format Tokens​

The formatDateTime plugin uses format tokens from the date-fns library. Here are some common tokens:

  • yyyy: 4-digit year
  • MM: 2-digit month
  • dd: 2-digit day of the month
  • HH: 2-digit hour (24-hour clock)
  • mm: 2-digit minute
  • ss: 2-digit second
  • MMMM: Full month name
  • do: Day of the month with ordinal
  • h: Hour (12-hour clock)
  • a: AM/PM indicator

For a full list of format tokens, refer to the date-fns format documentation.