A lightweight, promise-based TypeScript CalDAV client for syncing calendar data in browser, Node.js, or React Native environments.
ts-caldav helps you interact with CalDAV servers — allowing you to fetch calendars, manage events (including recurring events), and synchronize changes with minimal effort. Great for building calendar apps or integrations.
- Credential validation with CalDAV servers
- Fetch calendar homes and individual calendars
- List, create (including recurring), and delete events
- Detect event changes using
getctagandetag - Efficient sync with diff-based event updates
- Built for TypeScript, with full type safety
npm install ts-caldav
# or
pnpm install ts-caldav
# or
yarn add ts-caldavimport { CalDAVClient } from "ts-caldav";
const client = await CalDAVClient.create({
baseUrl: "https://caldav.example.com",
auth: {
type: "basic",
username: "myuser",
password: "mypassword",
}
});
// List calendars
const calendars = await client.getCalendars();
// Fetch events
const events = await client.getEvents(calendars[0].url);Here are some server endpoints that ts-caldav has been tested with:
| Provider | Endpoint Example |
|---|---|
https://apidata.googleusercontent.com/ |
|
| iCloud | https://caldav.icloud.com/ |
| Yahoo | https://caldav.calendar.yahoo.com |
| GMX | https://caldav.gmx.net |
💡 Note: Some servers may require enabling CalDAV support or generating app-specific passwords (especially iCloud and Fastmail).
Creates and validates a new CalDAV client instance.
const client = await CalDAVClient.create({
baseUrl: "https://caldav.example.com",
auth: {
type: "basic",
username: "john",
password: "secret",
},
logRequests: true,
});Returns an array of available calendars for the authenticated user.
Fetches events within a given time range (defaults to 3 weeks ahead if none provided). When all is true and no time range is provided the Client fetches all Events.
const events = await client.getEvents(calendarUrl, {
start: new Date(),
end: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // 1 week from now
all: false
});Returned Event objects include startTzid and endTzid (if defined in the calendar).
Creates a new calendar event. Supports:
- Full-day events (
wholeDay: true) - Recurring events (
recurrenceRule) - Timezone-aware events (
startTzid,endTzid)
await client.createEvent(calendar.url, {
summary: "Team Sync",
start: new Date("2025-07-01T09:00:00"),
end: new Date("2025-07-01T10:00:00"),
startTzid: "Europe/Berlin",
endTzid: "Europe/Berlin",
alarms: [
{
action: "DISPLAY",
trigger: "-PT30M",
description: "Popup reminder",
},
{
action: "AUDIO",
trigger: "-PT15M",
},
{
action: "EMAIL",
trigger: "-PT10M",
summary: "Email Reminder",
description: "Meeting coming up",
attendees: ["mailto:[email protected]"],
},
],
});If startTzid and endTzid are omitted, the event will be stored in UTC.
To use full timezone definitions (e.g., for legacy CalDAV servers), you may optionally include your own VTIMEZONE component via raw iCal data.
⚠️ ETag Notice Some CalDAV servers like Yahoo do not return anETagheader when creating events. BecauseETagis required to safely update events, callingupdateEventon strict CalDAV servers may fail unless theETagis manually retrieved viaPROPFIND.You can use the getETag() function to manually fetch the ETag
Deletes an event by UID. Optionally provide ETag for safe deletion.
Compares remote calendar state to local references using getctag and etag.
Returns a structure with:
changednewCtagnewEventsupdatedEventsdeletedEvents
Fetches full .ics data for specific event hrefs.
Fetches the current ETag for a specific event.
This is useful for servers (like Yahoo) that do not return the ETag after event creation. You can retrieve it manually using the event's href before performing an update or deletion that requires an ETag.
const etag = await client.getETag("/calendars/user/calendar-id/event-id.ics");
await client.updateEvent(calendarUrl, {
uid: "event-id",
href: "/calendars/user/calendar-id/event-id.ics",
etag,
summary: "Updated summary",
start: new Date(),
end: new Date(Date.now() + 60 * 60 * 1000),
});href:string– The full CalDAV URL of the.icsevent resource.
- A
Promise<string>resolving to theETagvalue. Throws if the ETag is not found or the request fails.
ℹ️ This method automatically strips weak validator prefixes (e.g.,
W/"...") for safe use withIf-Match.
The library supports per-event timezones using startTzid and endTzid fields:
await client.createEvent(calendar.url, {
summary: "Flight to SF",
start: new Date("2025-07-01T15:00:00"),
end: new Date("2025-07-01T18:00:00"),
startTzid: "Europe/Berlin",
endTzid: "America/Los_Angeles",
});When fetching events, startTzid and endTzid will be parsed (if present in the VEVENT) so that you can:
- Correctly interpret time in the user's zone
- Normalize across time zones for scheduling
If no TZID is set, dates are treated as UTC.
Supports the following recurrence rule fields:
freq: "DAILY", "WEEKLY", "MONTHLY", "YEARLY"interval: number of frequency intervals between occurrencescount: number of total occurrencesuntil: date until which the event recursbyday,bymonthday,bymonth
Example:
recurrenceRule: {
freq: "MONTHLY",
interval: 1,
byday: ["FR"],
until: new Date("2025-12-31"),
}- Supports Basic Auth and OAuth2
- Compatible with most CalDAV servers: Google, iCloud, Fastmail, Nextcloud, Radicale
const result = await client.syncChanges(calendar.url, lastCtag, localEventRefs);
if (result.changed) {
const newEvents = await client.getEventsByHref(calendar.url, [
...result.newEvents,
...result.updatedEvents,
]);
updateLocalDatabase(newEvents, result.deletedEvents);
saveNewCtag(result.newCtag);
}- Does not support WebDAV
sync-token(usegetctagdiffing instead) - Limited to
VEVENTcomponents only
git clone https://github.com/yourname/ts-caldav.git
cd ts-caldav
npm install
npm run buildContributions are very welcome! Take a look at CONTRIBUTING to get started.
- Basic CalDAV client with calendar and event support
- Recurring event support (RRULE)
- Timezone-aware event parsing and creation
- WebDAV sync-token support
- VTODO and VJURNAL support
This project is licensed under the MIT License. See the LICENSE file for details.