sanity-plugin-recurring-dates

This is a Sanity Studio v3 plugin.

This is a plugin to add a custom input component to your Sanity Studio which allows you to specify recurring dates.

The plugin allows for easy selection of common recurrences, as well as configuring custom recurrences. It's also possible to provide an end to a recurrence by setting an end date or a count of how many times the recurrnce should happen.

Installation

npm install sanity-plugin-recurring-dates

Usage

Add it as a plugin in sanity.config.ts (or .js):

import {defineConfig} from 'sanity'
import {recurringDates} from 'sanity-plugin-recurring-dates'

export default defineConfig({
  //...
  plugins: [recurringDates()],
})

In your schema, you can then set a field to use the recurringDates field type:

defineField({
  name: 'date',
  title: 'Date',
  type: 'recurringDates',
})

Configuring the plugin

You can configure the plugin on the plugin or field level. Plugin level configuration can be overridden on each field.

Plugin config

export default defineConfig({
  //...
  plugins: [
    recurringDates({
      // An array of RRULE strings to use as default recurrences
      defaultRecurrences: [
        'RRULE:FREQ=DAILY;INTERVAL=1',
        'RRULE:FREQ=WEEKLY;INTERVAL=1',
        'RRULE:FREQ=MONTHLY;INTERVAL=1',
        'RRULE:FREQ=YEARLY;INTERVAL=1',
      ],

      // Hides the end date field
      hideEndDate: true, // defaults to false

      // Hides the custom recurrence options
      hideCustom: true, // defaults to false

      // Configure the datepickers
      // See https://www.sanity.io/docs/datetime-type#options
      dateTimeOptions: {
        dateFormat: 'DD/MM/YYYY',
        timeFormat: 'HH:mm',
        timeStep: 15,
        displayTimeZone: 'Europe/London',
        allowTimeZoneSwitch: false,
      },

      // Changes the date picker to date only, no time
      dateOnly: true, // defaults to false

      // Change the field titles and descriptions
      // field names will remain "startDate" and "endDate"
      fieldTitles: {
        startDate: 'Event starts',
        endDate: 'Event ends',
      },
      fieldDescriptions: {
        startDate: 'This is the date the event starts',
        endDate: 'This is the date the event ends',
      },
    }),
  ],
})

Field config

defineField({
  name: 'date',
  title: 'Date',
  type: 'recurringDates',
  options: {
    // An array of RRULE strings to use as default recurrences
    defaultRecurrences: [
      'RRULE:FREQ=DAILY;INTERVAL=1',
      'RRULE:FREQ=WEEKLY;INTERVAL=1',
      'RRULE:FREQ=MONTHLY;INTERVAL=1',
      'RRULE:FREQ=YEARLY;INTERVAL=1',
    ],

    // Hides the end date field
    hideEndDate: true, // defaults to false

    // Hides the custom recurrence options
    hideCustom: true, // defaults to false

    // Configure the datepickers
    // See https://www.sanity.io/docs/datetime-type#options
    dateTimeOptions: {
      dateFormat: 'DD/MM/YYYY',
      timeFormat: 'HH:mm',
      timeStep: 15,
      displayTimeZone: 'Europe/London',
      allowTimeZoneSwitch: false,
    },

    // Changes the date picker to date only, no time
    dateOnly: true, // defaults to false

    // override the default validation
    validation: {
      startDate: (Rule) => Rule.required() // defaults to (Rule) => Rule.required()
      endDate: (Rule) => Rule.min(Rule.valueOfField('startDate')) // defaults to (Rule) => Rule.min(Rule.valueOfField('startDate'))
    }

    // Change the field titles and descriptions
    // field names will remain "startDate" and "endDate"
    fieldTitles: {
      startDate: 'Event starts',
      endDate: 'Event ends',
    },
    fieldDescriptions: {
      startDate: 'This is the date the event starts',
      endDate: 'This is the date the event ends',
    },
  },
})

Content

Here is an example of the data stored on the field after configuring a recurring date:

{
  "rrule": "RRULE:FREQ=MONTHLY;INTERVAL=1;BYDAY=+1MO",
  "startDate": "2023-08-01T12:47:00.000Z",
  "endDate": "2023-08-01T15:15:00.000Z"
}

As the plugin uses the standard Sanity datetime field type, the start and end dates are stored in UTC. The rrule string is in line with the recurrence rules defined in the iCalendar RFC, with rules generated by the rrule.js library.

If you enable the dateOnly option, then the time will not be present on the field:

{
  "rrule": "RRULE:FREQ=MONTHLY;INTERVAL=1;BYDAY=+1MO",
  "startDate": "2023-08-01",
  "endDate": "2023-08-01"
}

Depending on how you use the data, you may need to append a time to the date before using it on your front-end.

Using the rules on a frontend

Whilst displaying the recurring dates on a frontend is beyond the scope of this plugin, there are a couple of considerations worth calling out.

As the start dates are stored in UTC, which is a "floating" time, you need to process these into the timezone you want to display the dates in. You'll also need to think about Daylight Saving Time (DST) in these timezones.

By using the rrule and date-fns-tz libraries, you can achieve this in a similar manner to the below:

import {rrulestr} from 'rrule'
import {formatInTimeZone, getTimezoneOffset} from 'date-fns-tz'

// your desired timezone
const timezone = 'Europe/London'

// Start date as a date
const startDate = new Date(recurringDate.startDate)

// Pass your rrule and startDate to the `rrulestr` function
const upcomingRule = rrulestr(recurringDate.rrule, {
  dtstart: startDate,
})

// Calculate the offset from UTC for your timezone at the start date
const initialOffset = getTimezoneOffset(timezone, startDate)

// Map through all the rules, returning an array of dates in the correct timezone
// with consideration for changes in timezone offset as a result of DST
const allDates = rule.all().map((date) => {
  // Calculate the offset from UTC for your timezone at this recurrence
  const dateOffset = getTimezoneOffset(timezone, date)

  // Calculate the difference between the initial offset and this offset
  const diff = initialOffset - dateOffset

  // Adjust the date by the difference
  date.setTime(date.getTime() + diff)

  // Return a formatted date from the date needed, with the format we pass
  // in the third parameter
  return formatInTimeZone(date, timezone, 'EEEE, MMMM d, yyyy h:mm aaaa')
})

License

MIT © Tom Smith

Develop & test

This plugin uses @sanity/plugin-kit with default configuration for build & watch scripts.

See Testing a plugin in Sanity Studio on how to run this plugin with hotreload in the studio.

Release new version

Run "CI & Release" workflow. Make sure to select the main branch and check "Release new version".

Semantic release will only release on configured branches, so it is safe to run release on any branch.