simple-ics-calendar

A lightweight library for generating .ics calendar file with timezone, recurrence (RRULE), and multi-event support.

Table of Contents

• Overview
• Features
• Tech Stack
• Quick Start
  • Prerequisites
  • Installation
  • Usage
• API / Examples
  • Basic Event
  • Timezone Event
  • Recurring Event (RRULE)
  • All-Day Events
  • Email Attachment Example
• Options Reference
• Repository Structure
• Contributing
• Code of Conduct
• License

Overview

simple-ics-calendar is a library for generating .ics calendar files compatible with:

• Google Calendar
• Apple Calendar
• Outlook
• Yahoo
• Any iCalendar-compatible client

It is ideal for applications that send event invitations and scheduling emails.

Features

• Generate standard-compliant .ics files
• Timezone support (IANA: Africa/Lagos, Europe/London, etc.)
• Recurring events via RRULE (daily, weekly, monthly, yearly)
• All-day event support
• Organizer & attendee support
• Alarm & reminders (VALARM)
• Multi-event calendars
• Zero dependencies, lightweight and fast

Tech Stack

• TypeScript
• Node.js compatible
• Works in Browser + Server
• Outputs CommonJS + ESModule builds

Quick Start

Prerequisites

• Node.js 14+
• npm or yarn

Installation

npm install simple-ics-calendar
# or
yarn add simple-ics-calendar

Usage

import { buildCalendar, CalendarEventOptions } from "simple-ics-calendar";

const event: CalendarEventOptions = {
  title: "Product Demo Call",
  description: "Walkthrough with the customer",
  location: "Zoom",
  url: "https://zoom.us/my/demo",
  start: "2025-03-20T13:00:00Z",
  end:   "2025-03-20T14:00:00Z",
  isUtc: true,
  organizer: {
    name: "Ayodele Leom",
    email: "[email protected]"
  },
  attendees: [
    { name: "Customer A", email: "[email protected]", role: "REQ-PARTICIPANT" }
  ]
};

const icsContent = buildCalendar(event);

Examples

Basic Event

const event: CalendarEventOptions = {
  title: "Team Standup",
  start: "2025-05-01T10:00:00Z",
  end:   "2025-05-01T10:15:00Z",
  isUtc: true
};

buildCalendar(event);

Timezone Event

const event: CalendarEventOptions = {
  title: "Engineering Sync",
  start: "2025-05-01T09:00:00",
  end:   "2025-05-01T10:00:00",
  timeZone: "Africa/Lagos"
};

const ics = buildCalendar(event);

Recurring Event (RRULE)

const recurring: CalendarEventOptions = {
  title: "Weekly Product Review",
  start: "2025-04-01T09:00:00Z",
  end:   "2025-04-01T10:00:00Z",
  isUtc: true,
  recurrence: {
    freq: "WEEKLY",
    interval: 1,
    byWeekday: ["TU"],
    count: 12
  }
};

buildCalendar(recurring);

All-Day Events

const holiday: CalendarEventOptions = {
  title: "Public Holiday",
  start: "2025-12-25",
  end: "2025-12-26",
  allDay: true
};

buildCalendar(holiday);

Email Attachment Example

import nodemailer from "nodemailer";
import { buildCalendar } from "simple-ics-calendar";

const ics = buildCalendar(event);

await transport.sendMail({
  to: "[email protected]",
  subject: "Your Event Invitation",
  text: "Please find the attached calendar invitation.",
  attachments: [
    {
      filename: "invite.ics",
      content: ics,
      contentType: "text/calendar; charset=utf-8"
    }
  ]
});

Options Reference

CalendarEventOptions

| Field | Type | Description | |-------|------|-------------| | title | string | Event title (required) | | start | Date/string | Start of event | | end | Date/string | End of event | | allDay | boolean | Use all-day formatting | | timeZone | string | IANA timezone | | isUtc | boolean | Force UTC formatting | | location | string | Event location | | description | string | Event description | | url | string | Event URL | | organizer | {name,email} | Organizer info | | attendees | Attendee[] | Participants | | recurrence | RecurrenceRule | RRULE definition | | alarms | AlarmOptions[] | Event reminders |

Repository Structure

/simple-ics-calendar
├── src/
│   ├── index.ts
│   ├── types.ts
│   ├── builders/
│   │   ├── calendar.ts
│   │   ├── event.ts
│   │   └── rrule.ts
│   └── utils/
│       ├── datetime.ts
│       └── escape.ts
├── dist/
├── package.json
├── tsconfig.json
├── README.md
└── LICENSE

Contributing

Want to contribute data or improvements? See CONTRIBUTION.md for the full guide, dev setup, and PR checklist.

Code of Conduct

We follow the Contributor Covenant. Please adhere to respectful interactions.

License

MIT - see License.