vcf-to-json-converter

A lightweight, fast, and reliable Node.js library to convert VCF (vCard) files to structured JSON format with full CLI support.

const { vcfToJsonFromFile } = require("vcf-to-json-converter");

const contacts = vcfToJsonFromFile("./contacts.vcf");
console.log(contacts);

Table of Contents

• Features
• Installation
• Quick Start
• Usage
  • Command Line Interface
  • Programmatic Usage
  • TypeScript
• API Reference
• Output Format
• Supported vCard Fields
• Examples
• Troubleshooting
• Contributing
• License

Features

• Complete VCF Support - Convert VCF/vCard files (v2.1, v3.0, v4.0) to structured JSON
• Programmatic API - Easy integration into Node.js applications
• CLI Tool - Command-line interface for quick conversions
• Robust Error Handling - Comprehensive error handling and validation
• Rich Data Extraction - Extracts all contact information including photos, organizations, and notes
• TypeScript Ready - Full TypeScript definitions included
• High Performance - Efficiently processes large VCF files with multiple contacts
• Cross Platform - Works on Windows, macOS, and Linux
• Zero Dependencies - No external dependencies for maximum compatibility
• UTF-8 Support - Handles international characters and emojis correctly

Installation

Using npm:

npm install vcf-to-json-converter

For global CLI usage:

npm install -g vcf-to-json-converter

Using yarn:

yarn add vcf-to-json-converter

Quick Start

# Install globally for CLI
npm install -g vcf-to-json-converter

# Convert a VCF file
vcf-to-json contacts.vcf output.json

// Use in your Node.js project
const { vcfToJsonFromFile } = require("vcf-to-json-converter");

const contacts = vcfToJsonFromFile("./contacts.vcf");
console.log(`Converted ${contacts.length} contacts`);

Usage

Command Line Interface

# Convert and display JSON in terminal
vcf-to-json contacts.vcf

# Convert and save to file
vcf-to-json contacts.vcf output.json

# Convert with compact formatting (minified JSON)
vcf-to-json contacts.vcf output.json --compact

# Show help and version
vcf-to-json --help
vcf-to-json --version

Programmatic Usage

const {
  vcfToJson,
  vcfToJsonFromFile,
  saveJsonToFile,
} = require("vcf-to-json-converter");

// Method 1: Convert VCF text content
const vcfContent = `BEGIN:VCARD
VERSION:3.0
FN:John Doe
N:Doe;John;;;
TEL;TYPE=CELL:+1234567890
EMAIL;TYPE=HOME:[email protected]
ORG:ACME Corp
TITLE:Software Engineer
END:VCARD`;

const contacts = vcfToJson(vcfContent);
console.log("Parsed contacts:", contacts.length);

// Method 2: Convert VCF file directly
try {
  const contacts = vcfToJsonFromFile("./contacts.vcf");
  console.log(`Converted ${contacts.length} contacts`);

  // Save to JSON file with pretty formatting
  saveJsonToFile(contacts, "./output.json", true);

  // Access contact data
  contacts.forEach((contact) => {
    console.log(
      `${contact.fullName}: ${contact.phones.length} phones, ${contact.emails.length} emails`
    );
  });
} catch (error) {
  console.error("Conversion failed:", error.message);
}

TypeScript

import { vcfToJsonFromFile, Contact } from "vcf-to-json-converter";

const contacts: Contact[] = vcfToJsonFromFile("./contacts.vcf");
console.log(contacts);

API Reference

vcfToJson(vcfText: string): Contact[]

Converts VCF text content to JSON.

Parameters:

• vcfText (string): The VCF content as a string

Returns: Array of contact objects

Throws: Error if VCF content is invalid

Example:

const contacts = vcfToJson("BEGIN:VCARD\nVERSION:3.0\nFN:John Doe\nEND:VCARD");

vcfToJsonFromFile(filePath: string): Contact[]

Converts a VCF file to JSON.

Parameters:

• filePath (string): Path to the VCF file

Returns: Array of contact objects

Throws: Error if file doesn't exist or is invalid

Example:

const contacts = vcfToJsonFromFile("./my-contacts.vcf");

saveJsonToFile(jsonData: Contact[], outputPath: string, prettyPrint?: boolean): void

Saves JSON data to a file.

Parameters:

• jsonData (Contact[]): The JSON data to save
• outputPath (string): Path where to save the JSON file
• prettyPrint (boolean, optional): Whether to format JSON with indentation (default: true)

Example:

saveJsonToFile(contacts, "./output.json", true); // Pretty formatted
saveJsonToFile(contacts, "./compact.json", false); // Minified

Output Format

Each contact is converted to the following JSON structure:

{
  "fullName": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "phones": [
    {
      "value": "+1234567890",
      "type": "CELL"
    }
  ],
  "emails": [
    {
      "value": "[email protected]",
      "type": "HOME"
    }
  ],
  "organization": "ACME Corp",
  "title": "Software Engineer",
  "note": "Important contact",
  "photo": "",
  "url": "",
  "raw": {
    /* Original parsed vCard object */
  }
}

Supported vCard Fields

• Name: Full name, first name, last name
• Phone: Multiple phone numbers with types
• Email: Multiple email addresses with types
• Organization: Company/organization name
• Title: Job title
• Note: Notes/comments
• Photo: Photo data (base64)
• URL: Website URLs
• Raw: Complete original vCard data

Error Handling

The library provides comprehensive error handling for:

• Invalid file paths
• Missing files
• Permission errors
• Malformed VCF content
• Invalid input parameters

Examples

Basic Conversion

const { vcfToJsonFromFile } = require("vcf-to-json-converter");

const contacts = vcfToJsonFromFile("my-contacts.vcf");
console.log(`Found ${contacts.length} contacts`);

contacts.forEach((contact) => {
  console.log(
    `${contact.fullName}: ${contact.phones.map((p) => p.value).join(", ")}`
  );
});

Advanced Usage with Error Handling

const { vcfToJsonFromFile, saveJsonToFile } = require("vcf-to-json-converter");

try {
  // Convert VCF file
  const contacts = vcfToJsonFromFile("./contacts.vcf");

  // Filter contacts with email addresses
  const contactsWithEmail = contacts.filter(
    (contact) => contact.emails.length > 0
  );

  // Extract business contacts
  const businessContacts = contacts.filter((contact) => contact.organization);

  console.log(
    `Total: ${contacts.length}, With Email: ${contactsWithEmail.length}, Business: ${businessContacts.length}`
  );

  // Save different formats
  saveJsonToFile(contacts, "./all-contacts.json", true); // Pretty
  saveJsonToFile(businessContacts, "./business-contacts.json", false); // Compact
} catch (error) {
  if (error.code === "ENOENT") {
    console.error("File not found. Please check the file path.");
  } else {
    console.error("Conversion error:", error.message);
  }
}

Batch Processing

const fs = require("fs");
const path = require("path");
const { vcfToJsonFromFile, saveJsonToFile } = require("vcf-to-json-converter");

const vcfFiles = fs
  .readdirSync("./vcf-files")
  .filter((f) => f.endsWith(".vcf"));

vcfFiles.forEach((file) => {
  try {
    const contacts = vcfToJsonFromFile(path.join("./vcf-files", file));
    const outputFile = file.replace(".vcf", ".json");
    saveJsonToFile(contacts, path.join("./json-output", outputFile));
    console.log(`Converted ${file} (${contacts.length} contacts)`);
  } catch (error) {
    console.error(`Failed to convert ${file}:`, error.message);
  }
});

Troubleshooting

Common Issues

File not found error:

Error: ENOENT: no such file or directory

• Ensure the VCF file path is correct
• Use absolute paths if relative paths don't work
• Check file permissions

Invalid VCF format:

Error: Invalid VCF format

• Ensure your file starts with BEGIN:VCARD and ends with END:VCARD
• Check for corrupted or incomplete vCard entries
• Validate the VCF file structure

Empty output:

• Check if the VCF file contains properly formatted vCard entries
• Ensure the file encoding is UTF-8
• Verify the VCF version is supported (v2.1, v3.0, v4.0)

CLI command not found:

'vcf-to-json' is not recognized as an internal or external command

• Reinstall globally: npm install -g vcf-to-json-converter
• Check your PATH environment variable
• Try using npx vcf-to-json-converter instead

CLI Examples

# Show help
vcf-to-json --help

# Convert single file
vcf-to-json contacts.vcf

# Convert and save to specific file
vcf-to-json contacts.vcf my-contacts.json

# Compact output
vcf-to-json contacts.vcf contacts.json --compact

Requirements

• Node.js 12.0.0 or higher
• npm 6.0.0 or higher

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/shubhanshurav/vcf-to-json.git
cd vcf-to-json

# Install dependencies (if any)
npm install

# Run tests
npm test

# Test CLI locally
node index.js contacts.vcf

License

MIT License - see LICENSE file for details.

Author

Shubhanshu Rao

• GitHub: @shubhanshurav
• Repository: vcf-to-json

Links

• npm package
• GitHub repository
• Report Issues
• Changelog

Version History

v1.0.0 (Latest)

• Initial release
• CLI support with global installation
• Comprehensive vCard field parsing (v2.1, v3.0, v4.0)
• Robust error handling and validation
• TypeScript definitions included
• UTF-8 and international character support
• Zero dependencies for maximum compatibility

Star this repository if you find it helpful!