iCalKit

iCalendar file management - CLI tools and Node.js API for working with .ics files.

Features

• Split - Split large iCal files into smaller chunks for easy import into Google Calendar
• Merge - Combine multiple iCal files into one with duplicate detection
• View - View and browse iCal file contents (Coming Soon)
• Clean - Remove duplicate events and clean up your calendar (Coming Soon)

Web Application

A browser-based version is available at https://icalkit.app

Installation

npm install -g icalkit

CLI Usage

Split

Split a large iCal file into smaller chunks:

# Basic split (default: 1000 events per file)
icalkit split calendar.ics -o output/

# Custom chunk size
icalkit split calendar.ics -o output/ --chunk-size 500

# Sort events before splitting
icalkit split calendar.ics -o output/ --sort-by start-asc

Merge

Combine multiple iCal files:

# Basic merge
icalkit merge cal1.ics cal2.ics -o merged.ics

# With duplicate handling
icalkit merge cal1.ics cal2.ics -o merged.ics --duplicates remove

# With custom calendar name
icalkit merge cal1.ics cal2.ics -o merged.ics --name "My Calendar"

Duplicate handling options:

• warn (default) - Keep all events, warn about duplicates
• remove - Remove duplicate events (keep first occurrence)
• keep-all - Keep all events without warnings

API Usage

import { split, merge, parseCalendar, extractEvents } from 'icalkit';

// Split a calendar
const result = await split(icsContent, { chunkSize: 500 });
console.log(result.chunks); // Array of ICS strings

// Merge calendars
const merged = await merge([icsContent1, icsContent2], {
  duplicates: 'remove',
  calendarName: 'Merged Calendar',
});
console.log(merged.content); // Merged ICS string

// Parse and extract events
const calendar = parseCalendar(icsContent);
const events = extractEvents(calendar.vevents);

Development

Requirements

• Node.js >= 24.12.0
• pnpm >= 10.27.0

Setup

# Clone the repository
git clone https://github.com/sanrakudo/icalkit.git
cd icalkit

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test:run

# Check formatting and linting
pnpm check

Using mise (recommended)

This project uses mise for managing tool versions.

# Install mise
curl https://mise.run | sh

# Install tools (Node.js and pnpm)
mise install

Publishing

This project uses release-please for automated releases.

1. Commit using Conventional Commits:

   git commit -m "feat: add new feature"
   git commit -m "fix: resolve bug"

2. Push to main branch

3. release-please automatically creates release PRs and publishes to npm

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Acknowledgments

• Built with ical.js for iCalendar parsing