@sebbo2002/ical-generator@10.0.0

Built and signed on GitHub Actions

Built and signed on GitHub Actions

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

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, 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, timezones-ical-library or @touch4it/ical-timezones can be used for this:

Example with @touch4it/ical-timezones

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

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

Example with timezones-ical-library

import { ICalCalendar } from 'ical-generator';
import { tzlib_get_ical_block } from 'timezones-ical-library';

const cal = new ICalCalendar();
cal.timezone({
    name: 'Europe/Berlin',
    generator: (tz) => tzlib_get_ical_block(tz)[0],
});
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

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