titanism / ical-generator

ical-generator is a small piece of code which generates ical calendar files

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.

⚠️ Migration to v6

In version 6 some breaking changes were made to make ical-generator even better. A short list of these breaking changes and how you can adapt your code can be found in our Migration Guide.

📦 Installation

npm install ical-generator

⚡️ Quick Start

import ical, {ICalCalendarMethod} from 'ical-generator';
import http from 'node:http';

const calendar = ical({name: 'my first iCal'});

// A method is required for outlook to display event as an invitation
calendar.method(ICalCalendarMethod.REQUEST);

const startTime = new Date();
const endTime = new Date();
endTime.setHours(startTime.getHours()+1);
calendar.createEvent({
    start: startTime,
    end: endTime,
    summary: 'Example Event',
    description: 'It works ;)',
    location: 'my room',
    url: 'http://sebbo.net/'
});

http.createServer((req, res) => {
    res.writeHead(200, {
        'Content-Type': 'text/calendar; charset=utf-8',
        'Content-Disposition': 'attachment; filename="calendar.ics"'
    });

    res.end(calendar.toString());
}).listen(3000, '127.0.0.1', () => {
    console.log('Server running at http://127.0.0.1:3000/');
});

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 and moment-timezone objects. 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:

import {ICalCalendar} from 'ical-generator';
import {getVtimezoneComponent} from '@touch4it/ical-timezones';

const cal = new ICalCalendar();
cal.timezone({
    name: 'FOO',
    generator: getVtimezoneComponent
});
cal.createEvent({
    start: new Date(),
    timezone: 'Europe/London'
});

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
npm run browser-test

🙋 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.