ics

When working with iCalendar (RFC5545) properties like DTSTART or DTEND, time values can be expressed in three distinct forms. Choosing the correct form depends on whether you are using local time, UTC, or a specific time zone reference.

1. Local Time: Use this for 'floating' time where no specific time zone is attached.
2. UTC Time: Append a Z to the end of the timestamp to indicate UTC.
3. Local Time with Time Zone Reference: Use the TZID parameter to specify a time zone (e.g., America/New_York).

Note: The TZID parameter MUST NOT be applied to DATE properties or properties already specified in UTC.

// FORM #1: DATE WITH LOCAL TIME
19980118T230000

// FORM #2: DATE WITH UTC TIME
19980119T070000Z

// FORM #3: DATE WITH LOCAL TIME AND TIME ZONE REFERENCE
TZID=America/New_York:19980119T020000

To use the ics library in your project, install it using npm:

npm install -S ics

If you are contributing to the ics repository, use the following commands:

Run tests and watch for changes:

npm start

Run tests once:

npm test

Build the project: Compiles ES6 files from src/ into vanilla JavaScript in dist/.

npm run build

You can add alarms to events by including an alarms array in the event object. Each alarm object can specify an action (e.g., 'audio'), a description, a trigger (using hours, minutes, and before), and repeat counts. For audio alarms on Mac, you can use attachType: 'VALUE=URI' and an attach property.

let ics = require("ics")
let alarms = []

// Example alarm configuration
alarms.push({
  action: 'audio',
  description: 'Reminder',
  trigger: {hours:2,minutes:30,before:true},
  repeat: 2,
  attachType:'VALUE=URI',
  attach: 'Glass'
})

let event = {
  productId:"myCalendarId",
  uid: "123" + "@ics.com",
  startOutputType:"local",
  start: [2023, 9, 17, 15, 26],
  end: [2023, 9, 17, 17, 56],
  title: "test here",
  alarms: alarms
}

console.log(ics.createEvents([event]).value)

Use createEvents(events, headerParams, callback) to generate a single iCalendar file containing multiple events.

• events: An array of event attribute objects.
• headerParams: (Optional) An object containing calendar header parameters, such as calName.

const ics = require('ics')

const { error, value } = ics.createEvents([
  {
    title: 'Lunch',
    start: [2018, 1, 15, 12, 15],
    duration: { minutes: 45 }
  },
  {
    title: 'Dinner',
    start: [2018, 1, 15, 12, 15],
    duration: { hours: 1, minutes: 30 }
  }
])

if (error) {
  console.log(error)
  return
}

console.log(value)

createEventsAsync(events[, headerAttributes]) is the async variant of createEvents. It returns a Promise that resolves to an object { error, value }.

Performance Note: This method is optimized for large batches. It yields to the event loop during iteration to prevent freezing the process and builds the output in parts to reduce string concatenation overhead.

• events: An array of attribute objects.
• headerAttributes (optional): An object merged with the first event (if events is not empty) to build the calendar header. If events is empty, headerAttributes is used alone to build the header.

const { createEventsAsync } = require('ics');

const events = [
  { start: [2000, 1, 5, 10, 0], duration: { hours: 1 }, title: 'Event 1' }
];

async function run() {
  const { error, value } = await createEventsAsync(events);
  if (!error) console.log(value);
}

For large batches of events, use createEventsAsync(events, headerAttributes). This method returns a Promise that resolves to { error, value }.

Unlike the synchronous version, createEventsAsync periodically yields to the event loop, preventing the generation process from blocking the Node.js or browser main thread for extended periods.

const { createEventsAsync } = require('ics')

async function run () {
  const { error, value } = await createEventsAsync([
    {
      title: 'Lunch',
      start: [2018, 1, 15, 12, 15],
      duration: { minutes: 45 }
    },
    {
      title: 'Dinner',
      start: [2018, 1, 15, 12, 15],
      duration: { hours: 1, minutes: 30 }
    }
  ])

  if (error) {
    console.log(error)
    return
  }

  console.log(value)
}

run()

Use createEvents(events[, headerParams, callback]) to generate an iCal-compliant VCALENDAR string containing multiple VEVENTs.

• events: An array of attribute objects (the same shape used in createEvent).
• headerParams (optional): Parameters for the calendar header. If omitted, they are read from the first event in the array.

If no callback is provided, it returns { error, value }. If a callback is provided, it uses the Node-style function(err, value) pattern.

const { createEvents } = require('ics');

const events = [
  { start: [2000, 1, 5, 10, 0], duration: { hours: 1 }, title: 'Event 1' },
  { start: [2000, 1, 6, 10, 0], duration: { hours: 1 }, title: 'Event 2' }
];

const { error, value } = createEvents(events);
if (!error) console.log(value);