vcard-contacts

Bidirectional vCard (VCF) ↔ contact-object / CSV converter. Zero-dependency, TypeScript-native, works in Node and the browser.

Parsing contact exports is fiddly: real .vcf files come in vCard 2.1 / 3.0 / 4.0, use folded lines, quoted-printable encoding, cram multiple contacts into one file, and frequently omit a trailing END:VCARD. This library handles all of that and gives you clean, flat contact objects — or goes the other way and builds valid vCards from loosely-keyed CSV rows.

Extracted from the engine behind vcftocsv.com.

Install

npm install vcard-contacts

Usage

vCard → contacts

import { parseVcf } from "vcard-contacts";

const contacts = parseVcf(vcfFileText);
// [{ full_name: "Jane Cooper", first_name: "Jane", last_name: "Cooper",
//    phone: "+15550100", email: "[email protected]", organization: "Acme Inc", ... }]

CSV → vCard

Header keys are matched fuzzily — First Name, firstname, and given_name all map to the given name, so you don't have to normalize your spreadsheet first.

import { csvToVcf } from "vcard-contacts";

const vcf = csvToVcf('Full Name,Mobile,E-mail\r\n"Ada Lovelace",999,[email protected]\r\n');
// BEGIN:VCARD … END:VCARD  (vCard 3.0)

contacts → CSV rows

import { parseVcf, contactsToRecords } from "vcard-contacts";

const rows = contactsToRecords(parseVcf(vcfFileText));
// [{ "Full Name": "Jane Cooper", "Phone": "+15550100", "Email": "[email protected]", ... }]
// hand these to any CSV stringifier

API

| Function | Signature | Notes | | --- | --- | --- | | parseVcf | (text: string) => Contact[] | Parses any number of contacts. Tolerant of missing END:VCARD. | | toVcf | (rows: Record<string,string>[]) => string | Builds vCard 3.0 from fuzzy-keyed rows. | | csvToVcf | (csv: string) => string | parseCsv + toVcf in one call. | | parseCsv | (text: string) => Record<string,string>[] | Minimal RFC-4180-ish CSV parser (quoted fields, CRLF/LF). | | contactsToRecords | (contacts: Contact[]) => Record<string,string>[] | Flatten contacts to labelled CSV records. | | CONTACT_COLUMNS | { key, label }[] | The canonical field set + display labels. |

The Contact shape

interface Contact {
  full_name: string; first_name: string; last_name: string;
  phone: string; phone_2: string;
  email: string; email_2: string;
  organization: string; title: string;
  address: string; website: string; birthday: string; notes: string;
}

What it handles

• vCard 2.1, 3.0, 4.0
• Folded / continuation lines (RFC 6350)
• Quoted-printable values (common in 2.1 exports from older phones)
• Multiple contacts per file
• Files missing the final END:VCARD
• Deriving a display name from structured N when FN is absent
• Up to two phones and two emails per contact
• vCard escaping (\, \; \n \\) in both directions

License

MIT © Zac Frulloni

Need a no-code, in-browser version (or the reverse, CSV → vCard, with a downloadable file)? Use vcftocsv.com — free, no signup.