{"id":15892,"library":"vcard-parser","title":"vCard Parser","description":"The `vcard-parser` library is a utility for parsing vCard data into JavaScript objects and converting JavaScript objects back into vCard strings. It is designed to be a simple, standalone solution compatible with both Node.js environments and web browsers. Currently stable at version 1.0.0, the package primarily targets CommonJS module systems, as indicated by its usage examples. While it offers core vCard parsing and generation capabilities, its 'simple' nature might imply a focus on common vCard patterns rather than full support for every obscure or bleeding-edge vCard specification variant. As a 1.0.0 release, its release cadence is likely stable with infrequent updates, and its key differentiator is its straightforward, no-frills approach to vCard manipulation.","status":"maintenance","version":"1.0.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/Heymdall/vcard","tags":["javascript"],"install":[{"cmd":"npm install vcard-parser","lang":"bash","label":"npm"},{"cmd":"yarn add vcard-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add vcard-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This library is primarily CommonJS. Attempting ESM `import` will result in an error.","wrong":"import vCard from 'vcard-parser';","symbol":"vCard","correct":"const vCard = require('vcard-parser');"},{"note":"The `parse` function is a method on the default export. Direct named import is not supported.","wrong":"import { parse } from 'vcard-parser';","symbol":"parse","correct":"const { parse } = require('vcard-parser'); // Destructuring after require"},{"note":"The `generate` function is a method on the default export. Direct named import is not supported.","wrong":"import { generate } from 'vcard-parser';","symbol":"generate","correct":"const { generate } = require('vcard-parser'); // Destructuring after require"}],"quickstart":{"code":"const vCard = require('vcard-parser');\n\nconst raw = 'BEGIN:VCARD\\r\\n' +\n          'FN:Forrest Gump\\r\\n' +\n          'N:Gump;Forrest;;Mr.;\\r\\n' +\n          'TEL;TYPE=HOME:78884545247\\r\\n' +\n          'END:VCARD';\n\n// Parse vCard data into a JavaScript object\nconst card = vCard.parse(raw);\n\nconsole.log('Parsed vCard object:', JSON.stringify(card, null, 2));\n/* Expected output:\n{\n  \"fn\": [\n    {\n      \"value\": \"Forrest Gump\"\n    }\n  ],\n  \"n\": [\n    {\n      \"value\": [\n        \"Gump\",\n        \"Forrest\",\n        \"\",\n        \"Mr.\",\n        \"\"\n      ]\n    }\n  ],\n  \"tel\": [\n    {\n      \"value\": \"78884545247\",\n      \"meta\": {\n        \"type\": [\n          \"HOME\"\n        ]\n      }\n    }\n  ]\n}\n*/\n\n// Generate vCard data from a JavaScript object\nconst generated = vCard.generate(card);\n\nconsole.log('\\nGenerated vCard string:\\n', generated);\n// Expected output: BEGIN:VCARD\\r\\nFN:Forrest Gump\\r\\nN:Gump;Forrest;;Mr.;\\r\\nTEL;TYPE=HOME:78884545247\\r\\nEND:VCARD\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"The library exclusively uses CommonJS (`require`) syntax. Projects using ESM (`import`) will encounter module resolution errors when attempting to import directly.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.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.","message":"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).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure the library is imported using `const vCard = require('vcard-parser');` in a CommonJS environment. For ESM, this package is not directly compatible.","cause":"Attempting to use `vCard.parse` when `vCard` was imported incorrectly or is `undefined`.","error":"TypeError: Cannot read properties of undefined (reading 'parse') OR vCard.parse is not a function"},{"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.","cause":"You are attempting to `require()` an ESM-only module in a CommonJS context, or `import` a CJS module without proper configuration.","error":"ERR_REQUIRE_ESM: Must use import to load ES Module: .../node_modules/vcard-parser/index.js"},{"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.","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).","error":"SyntaxError: Unexpected token 'export'"}],"ecosystem":"npm"}