Calendar

calendar stores calendars and their events in Postgres. A recurring event is one row with an RFC 5545 RRULE; occurrences() expands it in TypeScript with the same expandRule the reminders block uses, so both agree on every date. Editing one occurrence writes an override row, and editing "this and following" splits the series in two.

better-supabase sql add calendar

import { createCalendar } from "better-supabase/blocks/calendar";

The module requires tenant and access. With share-links it serves an iCal feed, with reminders each event gets a recurrence rule that reminders can attach to, and with outbox its events are recorded.

TablesCopy Anchor Link

An override has recurrence_id (the series row) and original_start (the occurrence it replaces) and shares the series' uid, as RECURRENCE-ID does in iCalendar. Members read through the tables' policies; every write goes through a function that checks calendar.write, or calendar.manage to create and delete calendars. Deleting a user keeps the events they created.

Events and occurrencesCopy Anchor Link

const calendar = createCalendar({ transport });

const { id: calendarId } = await calendar
  .createCalendar(organizationId, "Team", { tz: "Europe/Amsterdam" })
  .orThrow();

await calendar
  .save(calendarId, {
    title: "Stand-up",
    startsAt: Temporal.Instant.from("2026-03-23T08:00:00Z"),
    endsAt: Temporal.Instant.from("2026-03-23T08:15:00Z"),
    tz: "Europe/Amsterdam",
    rrule: "FREQ=WEEKLY;BYDAY=MO",
  })
  .orThrow();

const week = await calendar
  .occurrences([calendarId], {
    from: Temporal.Instant.from("2026-03-30T00:00:00Z"),
    until: Temporal.Instant.from("2026-04-06T00:00:00Z"),
  })
  .orThrow();

A series follows its tz: the stand-up stays at 09:00 in Amsterdam across the daylight saving change, so its UTC time moves. Each occurrence has a stable key (the series id and its original start), its start and end, and the event row that applies, which is the override when there is one.

editFollowing ends the old series the second before the occurrence (its COUNT becomes an UNTIL) and starts a new series there with the remaining count and a new uid. EXDATEs and overrides after the split move to the new series. splitRule(rrule, dtstart, at) computes both rules if you need them yourself.

iCalendarCopy Anchor Link

importIcs parses an RFC 5545 file and upserts its events by UID, and RECURRENCE-ID events become overrides of their series. Importing the same file again updates the events instead of duplicating them. exportIcs writes the calendar back, with a VTIMEZONE for every zone its events use.

const summary = await calendar.importIcs(calendarId, text).orThrow();
// { created: 12, updated: 0, skipped: 1 }

const ics = await calendar
  .exportIcs({ id: calendarId, name: "Team", tz: "Europe/Amsterdam" })
  .orThrow();

The parser and writer are in the package (parseIcs, toIcs): they unfold and fold lines at 75 octets, escape TEXT, and read TZID, UTC, floating and all-day times, DURATION, EXDATE, STATUS and ATTENDEE. VALARM and VTODO are skipped.

iCal feedCopy Anchor Link

With share-links installed, a share link to a calendar (subjectType: "calendar") works as a subscription URL. calendar_feed(token) is open to anon, hashes the token before the lookup and returns nothing for a revoked, expired or unknown token, or a link whose organization is not the calendar's.

const link = await shareLinks
  .create(organizationId, "calendar", calendarId, "view")
  .orThrow();

export async function GET(
  _request: Request,
  { params }: { params: Promise<{ token: string }> },
) {
  const { token } = await params;
  const ics = await calendar.feed(token).orThrow();
  if (ics === null) return new Response("Not found", { status: 404 });
  return new Response(ics, {
    headers: { "content-type": "text/calendar; charset=utf-8" },
  });
}

ReactCopy Anchor Link

useCalendar loads the occurrences of a visible range and returns them in the shape an event calendar renders. The hook is typed structurally, so it needs no UI library.

"use client";

import { useCalendar } from "better-supabase/blocks/calendar/react";

const { events, loading, editOccurrence, editFollowing, cancelOccurrence } =
  useCalendar({ calendarIds, range: { start, end } });

Each event's id is the occurrence key and its data is the occurrence, so a drop or a resize maps back with fromEventCalendarUpdate. toEventCalendarResources turns calendars into resources for a resource view; by default each event's resource is its calendar, and resourceOf picks another one, such as the event's subject.

HooksCopy Anchor Link

before_calendar_event_save(tenant, calendar, item) runs before an insert or update and can raise to refuse it; after_calendar_event_save(event) runs after it. See block hooks.

ErrorsCopy Anchor Link

With ReUICopy Anchor Link

ReUI's Event Calendar renders useCalendar's events directly: month, week, day and agenda views, drag to move and resize, and resource views from toEventCalendarResources. Install it with npx shadcn@latest add @reui/event-calendar; the free examples c-event-calendar-1 to c-event-calendar-5 show each view. The Pro blocks in the application/event-calendar category build full scheduling screens on it; their source is licensed per user, so copy them into your app from reui.io.