Options
All
  • Public
  • Public/Protected
  • All
Menu

ical-generator Logo

ical-generator

License Size Status Dependencies

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 from 'ical-generator';
import http from 'http';

const calendar = ical({name: 'my first iCal'});
calendar.createEvent({
    start: moment(),
    end: moment().add(1, 'hour'),
    summary: 'Example Event',
    description: 'It works ;)',
    location: 'my room',
    url: 'http://sebbo.net/'
});

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

📑 API-Reference

🕒 Date, Time & Timezones

ical-generator supports native Date, moment.js (and moment-timezone, Day.js and Luxon's DateTime 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 ical 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

I updated to ical-generator@2.x.x and now get TypeError: ical is not a function errors

If you still want to use require() to import in version 2 onwards, please use require('ical-generator').default. The reason for this change is that from version 2 on, other objects such as types and interfaces required for typescript are exported as well (#247).

What's Error: Can't resolve 'fs'?

ical-generator uses the node.js fs module to save your calendar on the filesystem. In browser environments, you usually don't need this, so if you pass null for fs in your bundler. In webpack this looks like this:

{
  "resolve": {
    "fallback": {
      "fs": false
    }
  }
}

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 use Typescript and get TS2307: Cannot find module errors

ical-generator supports some third-party libraries such as moment.js or Day.js. To enable Typescript to do something with these types, they must of course also be installed. Unfortunately, npm does not install peerDependencies in versions 4-6, so these dependencies have to be installed manually. The best thing to do is to update your npm installation and reinstall ical-generator, which should solve the problem.

🙆🏼‍♂️ Copyright and license

Copyright (c) Sebastian Pekarek under the MIT license.

Index

Type aliases

ICalAlarmTypeValue

ICalAlarmTypeValue: keyof ICalAlarmType

ICalDateTimeValue

ICalDateTimeValue: Date | Moment | MomentTZ | Dayjs | LuxonDateTime | string

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

Functions

default

  • Create a new, empty calendar and returns it.

    import ical from 'ical-generator';
    
    // or use require:
    // const ical = require('ical-generator').default;
    
    const cal = ical();
    

    You can pass options to setup your calendar or use setters to do this.

    import ical from 'ical-generator';
    
    // or use require:
    // const ical = require('ical-generator').default;
    const cal = ical({domain: 'sebbo.net'});
    
    // is the same as
    
    const cal = ical().domain('sebbo.net');
    
    // is the same as
    
    const cal = ical();
    cal.domain('sebbo.net');
    

    Parameters

    Returns ICalCalendar

escape

  • escape(str: string | unknown): string
  • Escapes special characters in the given string

    Parameters

    • str: string | unknown

    Returns string

foldLines

  • foldLines(input: string): string
  • Trim line length of given string

    Parameters

    • input: string

    Returns string

formatDate

  • formatDate(timezone: string | null, d: ICalDateTimeValue, dateonly?: boolean, floating?: boolean): string
  • Converts a valid date/time object supported by this library to a string.

    Parameters

    • timezone: string | null
    • d: ICalDateTimeValue
    • Optional dateonly: boolean
    • Optional floating: boolean

    Returns string

formatDateTZ

  • formatDateTZ(timezone: string | null, property: string, date: ICalDateTimeValue | Date | string, eventData?: { floating?: boolean | null; timezone?: string | null }): string
  • Converts a valid date/time object supported by this library to a string. For information about this format, see RFC 5545, section 3.3.5 https://tools.ietf.org/html/rfc5545#section-3.3.5

    Parameters

    • timezone: string | null
    • property: string
    • date: ICalDateTimeValue | Date | string
    • Optional eventData: { floating?: boolean | null; timezone?: string | null }
      • Optional floating?: boolean | null
      • Optional timezone?: string | null

    Returns string

Legend

  • Constructor
  • Method
  • Property

Generated using TypeDoc