contacts-to-calendar

Convert a Google Contacts CSV export into an .ics calendar file of recurring birthdays and anniversaries you can import into any calendar app (Google Calendar, Apple Calendar, Outlook, …).

Especially useful when you live in Germany, where Google Calendar no longer automatically imports birthdays from Google Contacts.

Your data remains private: the conversion happens entirely on your machine, and no data is sent to any server.

What it does

Reads a Google Contacts CSV and, for every contact, extracts:

• the Birthday column, and
• any custom events (Event N - Label / Event N - Value columns — e.g. Anniversary, Wedding Anniversary, Engagement, In Memory of).

Each entry becomes an all-day, yearly-recurring calendar event titled <Contact Name>'s <Label> (e.g. John Doe's Birthday).

Date handling

• Dates with a year (YYYY-MM-DD) keep that year as the anchor, so the event first appears in the past on its original date and repeats every year after. Scrolling back through your calendar shows birthdays alongside other past events.
• Year-less dates (Google's --MM-DD form) are anchored to the year 2000.
• Unparseable dates are skipped.

Contact names are assembled from the First Name / Middle Name / Last Name columns, falling back to Organization Name, then Unknown.

Requirements

• Node.js and npm.

Usage

Export your contacts from Google Contacts as a Google CSV, then run the CLI with the CSV path:

npx @alexwende/contacts-to-calendar contacts.csv

The output is written next to the input with a .ics extension (e.g. contacts.csv → contacts.ics) and can be imported directly into your calendar app.

From a local clone

npm install
npm run build          # compiles src/ → dist/
node dist/cli.js contacts.csv

As a library

Install the package and call the wrapper, which streams a CSV file and writes the .ics output:

import { contactsToCalendar } from "@alexwende/contacts-to-calendar";

// (input CSV path, output ICS path)
contactsToCalendar("contacts.csv", "contacts.ics");

The individual pipeline stages are exported too, so you can compose them yourself (e.g. to parse in-memory records or produce the .ics string without touching the filesystem):

import {
  eventsFromContact,          // CSV record  → contact events
  calendarEventsFromContactEvents, // contact events → ics event attributes
  calendarFromEvents,         // ics event attributes → .ics string
} from "@alexwende/contacts-to-calendar";

Project structure

• src/contacts.ts — parses a Google Contacts CSV record into contact events (name + label + date).
• src/calendar.ts — date normalization and conversion of contact events into iCalendar events and .ics output.
• src/contacts-to-calendar.ts — file-path wrapper that streams the CSV in and writes the .ics out.
• src/cli.ts — command-line entry point.
• src/index.ts — re-exports the modules above as the package's public API.

Dependencies

• csv-parser — streams and parses the contacts CSV.
• ics — builds the iCalendar (.ics) output.