Registry / serialization / ical.js

ical.js

JSON →
library2.2.1jsnpmunverified

ical.js is a JavaScript library designed for parsing and manipulating iCalendar (RFC 5545) and vCard (RFC 6350) data, along with their JSON counterparts jCal (RFC 7265) and jCard (RFC 7095). The library is currently at version 2.2.1 and maintains an active development cycle, regularly releasing updates that include bug fixes, performance improvements, and TypeScript type enhancements. Originally ported from libical with a focus on web compatibility, it provides a robust, dependency-free solution for handling calendar and contact data. A key differentiator is its dual distribution, offering both ES6 modules for modern environments and a transpiled ES5 CommonJS build for broader compatibility, particularly in older browser script tags. It also offers an optional, separate bundle for comprehensive IANA timezone definitions, acknowledging their size and update frequency.

npm install ical.js
INSTALL
IMPORT
SIG · ICAL.JS
I
ical.js
serializationjavascriptv2.2.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ICAL
✓ import ICAL from 'ical.js';
✗ const ICAL = require('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
✓ import { Component } from 'ical.js';
✗ import Component from 'ical.js/Component';
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
✓ import { Time } from 'ical.js';
✗ import Time from 'ical.js/Time';
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.

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();
Debug
Known issues
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`).
affects: >=2.0.0
gotchaThe 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.
affects: >=1.0.0
gotchaDirect 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>`.
affects: >=2.0.0
Errors
Common errors & fixes
ReferenceError: ICAL is not defined
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
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
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.
Upgrade
Version history
2.2.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
ical.js — npm install ical.js · libregistry