iCal.js - iCalendar and vCard Parser

Common errors

• ReferenceError: ICAL is not defined

  cause Attempting to use `ical.js` (v2.0.0+) in a CommonJS environment with `require()` or directly in a browser without `type="module"` or the ES5 build.
  fix Ensure you are using `import ICAL from 'ical.js';` in module-aware environments or include the `ical.es5.cjs` bundle for legacy browser script tags.

• TypeError: Cannot read properties of undefined (reading 'start') or incorrect recurrence calculations

  cause This typically occurs when dealing with recurring events that rely on timezone data, but the `ical.timezones.js` bundle has not been included, or timezone definitions are missing from the ICS file itself.
  fix Include `ical.timezones.js` in your project for comprehensive IANA timezone support. If issues persist, verify that the iCalendar data itself contains VTIMEZONE components if specific timezones are expected.

• ICAL.parse: expected ':' but found '...' at line X

  cause The input iCalendar or vCard string is malformed or contains syntax errors according to RFC specifications (e.g., missing colons, invalid property names, incorrect folding).
  fix Review the iCalendar/vCard string for syntax compliance. Tools like the `ical.js` online validator (`kewisch.github.io/ical.js/validator.html`) can help identify specific parsing issues and correct formatting errors.

Warnings

• breaking `ical.js` transitioned to ES6 modules in v2.0.0. This change breaks direct CommonJS `require()` usage with the main bundle, requiring module-aware environments or specific ES5 builds.
  Fix: For modern environments (Node.js or browser with build tools), use `import ICAL from 'ical.js';`. For direct browser `<script>` tags or older environments, include the `ical.es5.cjs` bundle (e.g., `https://unpkg.com/ical.js/dist/ical.es5.min.cjs`).
• gotcha The main `ical.js` package does not include IANA timezone definitions by default to reduce bundle size. Date calculations and recurrence expansions involving timezones will be inaccurate or incorrect without them.
  Fix: For timezone-aware operations, you must explicitly include the separate `ical.timezones.js` bundle. This can be done as an additional script or integrated into your build process to ensure comprehensive timezone data is available.
• gotcha Direct usage of the `ical.js` ES6 module via a browser `<script>` tag requires the `type="module"` attribute. Failing to include this or attempting to use it in older browser environments will lead to module loading errors.
  Fix: For modern browsers, use `<script type="module" src="https://unpkg.com/ical.js/dist/ical.min.js"></script>`. For broader compatibility or older environments, use the ES5 CommonJS build: `<script src="https://unpkg.com/ical.js/dist/ical.es5.min.cjs"></script>`.

Install

• npm install ical.js npm
• yarn add ical.js yarn
• pnpm add ical.js pnpm

Imports

• ICAL
  wrong:

  const ICAL = require('ical.js');

  correct:

  import ICAL from 'ical.js';

  Since v2.0.0, the primary `ical.js` bundle is an ES6 module. CommonJS `require()` is not directly supported without transpilation or using the `ical.es5.cjs` distribution.
• Component
  wrong:

  import Component from 'ical.js/Component';

  correct:

  import { Component } from 'ical.js';

  Core classes like `Component` and `Event` are available as named exports directly from the main package, or can be accessed via `ICAL.Component` after a default import.
• Time
  wrong:

  import Time from 'ical.js/Time';

  correct:

  import { Time } from 'ical.js';

  The `Time` class is used for handling iCalendar date and time objects, often in conjunction with `ICAL.Event` recurrence rules.
• Types

  import type { Component, Event, Time } from 'ical.js';

  TypeScript types are available since v2.1.0, enabling better type checking and IDE support for the library's classes and interfaces.

Quickstart

Demonstrates parsing an iCalendar string, accessing the calendar component, and iterating through its event components to log event summaries, locations, start times, and handle recurring events.

import ICAL from "ical.js";

async function parseAndDisplayCalendar() {
  const icsData = `BEGIN:VCALENDAR\nVERSION:2.0\nPRODID:-//Example Corp//NONSGML My Calendar//EN\nCALSCALE:GREGORIAN\nBEGIN:VEVENT\nUID:event1@example.com\nDTSTAMP:20230101T120000Z\nDTSTART:20230115T100000Z\nDTEND:20230115T110000Z\nSUMMARY:Team Meeting\nDESCRIPTION:Discuss Q1 planning and objectives.\nLOCATION:Conference Room A\nEND:VEVENT\nBEGIN:VEVENT\nUID:event2@example.com\nDTSTAMP:20230101T130000Z\nDTSTART:20230220T140000Z\nDURATION:PT1H30M\nSUMMARY:Project Deadline Review\nRRULE:FREQ=MONTHLY;COUNT=3\nEND:VEVENT\nEND:VCALENDAR`;

  try {
    const jcalData = ICAL.parse(icsData);
    const comp = new ICAL.Component(jcalData);

    console.log("Calendar events:");
    const events = comp.getAllSubcomponents('vevent');

    if (events.length === 0) {
      console.log("No events found.");
      return;
    }

    events.forEach((eventComp, index) => {
      const event = new ICAL.Event(eventComp);
      console.log(`\nEvent ${index + 1}:`);
      console.log(`  Summary: ${event.summary}`);
      console.log(`  Location: ${event.location || 'N/A'}`);
      console.log(`  Start: ${event.startDate.toString()}`);

      if (event.isRecurring()) {
        console.log(`  (Recurring Event - Rule: ${event.getFirstPropertyValue('rrule') ? event.getFirstPropertyValue('rrule').toString() : 'N/A'})`);
        const iterator = event.iterator();
        let occurrences = [];
        let next;
        // Get up to 5 occurrences
        for (let i = 0; i < 5 && (next = iterator.next()); i++) {
            occurrences.push(new ICAL.Time(next).toString());
        }
        if (occurrences.length > 0) {
            console.log(`  First 5 occurrences: ${occurrences.join(', ')}`);
        }
      } else {
        console.log(`  End: ${event.endDate.toString()}`);
      }
    });

  } catch (error) {
    console.error("Error parsing iCalendar data:", error);
  }
}

parseAndDisplayCalendar();