vCard Parser

Common errors

• TypeError: Cannot read properties of undefined (reading 'parse') OR vCard.parse is not a function

  cause Attempting to use `vCard.parse` when `vCard` was imported incorrectly or is `undefined`.
  fix Ensure the library is imported using `const vCard = require('vcard-parser');` in a CommonJS environment. For ESM, this package is not directly compatible.

• ERR_REQUIRE_ESM: Must use import to load ES Module: .../node_modules/vcard-parser/index.js

  cause You are attempting to `require()` an ESM-only module in a CommonJS context, or `import` a CJS module without proper configuration.
  fix This library is CommonJS. If you are in an ESM project, you cannot `import` it directly. You must use `require('vcard-parser')` within a CJS context or consider a different library.

• SyntaxError: Unexpected token 'export'

  cause You are trying to run a JavaScript file with ESM `import`/`export` syntax in an environment that only supports CommonJS by default (e.g., older Node.js versions without `--experimental-modules` or `"type": "module"` in package.json).
  fix This error is likely related to *your project's* configuration, not `vcard-parser` itself (which is CJS). Ensure your environment is configured for ESM if you are writing ESM, or revert to CommonJS syntax if not.

Warnings

• breaking The library exclusively uses CommonJS (`require`) syntax. Projects using ESM (`import`) will encounter module resolution errors when attempting to import directly.
  Fix: Use CommonJS `require` for importing. For ESM projects, consider a dynamic `import()` or a CommonJS wrapper if absolutely necessary, or use a different vCard library with native ESM support.
• gotcha The parser expects specific line endings (`\r\n`). Malformed vCard strings with incorrect line endings (`\n` only) or other formatting issues might lead to incorrect parsing or errors.
  Fix: Ensure input vCard strings adhere strictly to RFC 2426 (or subsequent) formatting, particularly regarding line endings and property syntax. Pre-process input strings to normalize line endings if necessary.
• gotcha As a 'simple' parser, `vcard-parser` might not fully support all advanced or proprietary vCard properties, custom extensions, or complex encoding schemes defined in later vCard specifications (e.g., vCard 4.0).
  Fix: Thoroughly test with diverse vCard inputs, especially those leveraging newer specifications or custom fields. For full RFC compliance across all vCard versions, a more robust and actively maintained library might be required.

Install

• npm install vcard-parser npm
• yarn add vcard-parser yarn
• pnpm add vcard-parser pnpm

Imports

• vCard
  wrong:

  import vCard from 'vcard-parser';

  correct:

  const vCard = require('vcard-parser');

  This library is primarily CommonJS. Attempting ESM `import` will result in an error.
• parse
  wrong:

  import { parse } from 'vcard-parser';

  correct:

  const { parse } = require('vcard-parser'); // Destructuring after require

  The `parse` function is a method on the default export. Direct named import is not supported.
• generate
  wrong:

  import { generate } from 'vcard-parser';

  correct:

  const { generate } = require('vcard-parser'); // Destructuring after require

  The `generate` function is a method on the default export. Direct named import is not supported.

Quickstart

This example demonstrates how to parse a raw vCard string into a JavaScript object and then convert that object back into a vCard string using the `vcard-parser` library.

const vCard = require('vcard-parser');

const raw = 'BEGIN:VCARD\r\n' +
          'FN:Forrest Gump\r\n' +
          'N:Gump;Forrest;;Mr.;\r\n' +
          'TEL;TYPE=HOME:78884545247\r\n' +
          'END:VCARD';

// Parse vCard data into a JavaScript object
const card = vCard.parse(raw);

console.log('Parsed vCard object:', JSON.stringify(card, null, 2));
/* Expected output:
{
  "fn": [
    {
      "value": "Forrest Gump"
    }
  ],
  "n": [
    {
      "value": [
        "Gump",
        "Forrest",
        "",
        "Mr.",
        ""
      ]
    }
  ],
  "tel": [
    {
      "value": "78884545247",
      "meta": {
        "type": [
          "HOME"
        ]
      }
    }
  ]
}
*/

// Generate vCard data from a JavaScript object
const generated = vCard.generate(card);

console.log('\nGenerated vCard string:\n', generated);
// Expected output: BEGIN:VCARD\r\nFN:Forrest Gump\r\nN:Gump;Forrest;;Mr.;\r\nTEL;TYPE=HOME:78884545247\r\nEND:VCARD