ical-generator is a small but fine library with which you can very easily create a valid iCal calendars, for example to generate subscriptionable calendar feeds.

📦 Installation

npm install ical-generator

⚡️ Quick Start

1import ical, { ICalCalendarMethod } from 'ical-generator';
2import http from 'node:http';
3
4const calendar = ical({ name: 'my first iCal' });
5
6// A method is required for outlook to display event as an invitation
7calendar.method(ICalCalendarMethod.REQUEST);
8
9const startTime = new Date();
10const endTime = new Date();
11endTime.setHours(startTime.getHours() + 1);
12calendar.createEvent({
13    start: startTime,
14    end: endTime,
15    summary: 'Example Event',
16    description: 'It works ;)',
17    location: 'my room',
18    url: 'http://sebbo.net/',
19});
20
21http.createServer((req, res) => {
22    res.writeHead(200, {
23        'Content-Type': 'text/calendar; charset=utf-8',
24        'Content-Disposition': 'attachment; filename="calendar.ics"',
25    });
26
27    res.end(calendar.toString());
28}).listen(3000, '127.0.0.1', () => {
29    console.log('Server running at http://127.0.0.1:3000/');
30});

See the examples folder for more examples.

📑 API-Reference

• Index
  • ICalCalendar
  • ICalEvent
    • ICalAlarm
    • ICalAttendee
    • ICalCategory

🕒 Date, Time & Timezones

ical-generator supports native Date, Day.js, Luxon's DateTime and the older moment.js, moment-timezone objects and TZDate. You can also pass a string which is then passed to javascript's Date internally.

It is recommended to use UTC time as far as possible. ical-generator will output all time information as UTC time as long as no time zone is defined. For day.js, a plugin is necessary for this, which is a prerequisite. If a time zone is set, ical-generator assumes that the given time matches the time zone. If a time zone is used, it is also recommended to use a VTimezone generator. Such a function generates a VTimezone entry and returns it. For example, ical-timezones can be used for this:

1import { ICalCalendar } from 'ical-generator';
2import { getVtimezoneComponent } from '@touch4it/ical-timezones';
3
4const cal = new ICalCalendar();
5cal.timezone({
6    name: 'FOO',
7    generator: getVtimezoneComponent,
8});
9cal.createEvent({
10    start: new Date(),
11    timezone: 'Europe/London',
12});

If a moment-timezone object or Luxon's setZone method works, ical-generator sets it according to the time zone set in the calendar/event.

🚦 Tests

npm test
npm run coverage

🙋 FAQ

Where's the changelog?

It's here. If you need the changelog for ical-generator 1.x.x and older, you'll find it here.

I get a ReferenceError: TextEncoder is not defined error (in some browsers)

This library uses TextEncoder, which is available in node.js ≥ 11.0.0 and all modern browsers. Outdated browsers may not have the necessary API and generate this error when generating the calendar.

🙆🏼‍♂️ Copyright and license

Copyright (c) Sebastian Pekarek under the MIT license.