ical-generator

When using timezones, it is recommended to use a VTimezone generator to ensure the calendar includes the necessary timezone definitions. You can pass a generator function to the calendar.timezone() method. This function should take a timezone name and return a VTimezone entry.

Using @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',
});

Using 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',
});

This example demonstrates how to initialize a calendar, set a required method for Outlook compatibility (using ICalCalendarMethod.REQUEST), create an event with specific details, and serve the resulting .ics file using a Node.js HTTP server.

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/');
});

The timezone method sets the timezone for the calendar. If a timezone is set, ical-generator assumes all provided dates are already in that timezone.

Using a Timezone Generator

For best support, you should provide a generator function. This function takes a timezone name (string) and returns a VTimezone component string. This allows the library to automatically include necessary VTIMEZONE entries in the iCal output for all timezones used by the calendar or its events.

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

const cal = ical();
cal.timezone({
    name: 'FOO',
    generator: getVtimezoneComponent
});

cal.createEvent({
    start: new Date(),
    timezone: 'Europe/London'
});

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

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

You can add events to a calendar using createEvent for single events or events for bulk addition.

Adding Events

• createEvent(data: ICalEvent | ICalEventData): Creates a new ICalEvent and adds it to the calendar. Returns the created event instance.
• events(events?: (ICalEvent | ICalEventData)[]): If provided with an array, it adds multiple events to the calendar. If called without arguments, it returns the array of all current ICalEvent objects.
• clear(): Removes all events from the calendar without affecting other metadata.
• length(): Returns the number of events currently in the calendar.

const cal = ical();

// Create a single event
const event = cal.createEvent({ summary: 'My Event' });
event.summary('Your Event');

// Add multiple events at once
cal.events([
    {
       start: new Date(),
       end: new Date(new Date().getTime() + 3600000),
       summary: 'Example Event',
       description: 'It works ;)',
       url: 'http://sebbo.net/'
    }
]);

// Get all events
const allEvents = cal.events();