{"id":15326,"library":"fast-xml-parser","title":"Fast XML Parser and Validator","description":"fast-xml-parser is a robust JavaScript library for parsing XML to JavaScript objects, validating XML syntactically, and historically, building XML from JS objects. It is engineered for speed and efficiency, capable of handling large XML files (tested up to 100MB) without relying on C/C++ native libraries. As of v5.7.1, the package is actively maintained with frequent minor and patch releases, incorporating performance improvements and dependency updates. A key differentiator is its pure JavaScript implementation, broad compatibility (CommonJS, ESM, and browser environments), and extensive support for various XML features including entities, unpaired tags, and customizable parsing options. The XML Builder functionality was separated into a dedicated `fast-xml-builder` package in version v5.4.0, focusing `fast-xml-parser` primarily on parsing and validation.","status":"active","version":"5.7.1","language":"javascript","source_language":"en","source_url":"https://github.com/NaturalIntelligence/fast-xml-parser","tags":["javascript","fast","xml","json","parser","xml2js","x2js","xml2json","js","typescript"],"install":[{"cmd":"npm install fast-xml-parser","lang":"bash","label":"npm"},{"cmd":"yarn add fast-xml-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add fast-xml-parser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Handles XML entity processing and expansion, integrated since v5.6.0.","package":"@nodable/entities","optional":false}],"imports":[{"note":"The primary class for parsing XML. Ensure named import for ESM; CommonJS needs object destructuring from `require()`.","wrong":"const XMLParser = require('fast-xml-parser');","symbol":"XMLParser","correct":"import { XMLParser } from 'fast-xml-parser';"},{"note":"Provides static methods for XML syntax validation. It is a named export, not a default export.","wrong":"import XMLValidator from 'fast-xml-parser';","symbol":"XMLValidator","correct":"import { XMLValidator } from 'fast-xml-parser';"},{"note":"TypeScript type definition for configuring the XMLParser instance.","symbol":"IXMLOptions","correct":"import type { IXMLOptions } from 'fast-xml-parser';"}],"quickstart":{"code":"import { XMLParser, XMLValidator } from 'fast-xml-parser';\n\nconst xmlData = `<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<bookstore>\n  <book category=\"cooking\">\n    <title lang=\"en\">Everyday Italian</title>\n    <author>Giada De Laurentiis</author>\n    <year>2005</year>\n    <price>30.00</price>\n  </book>\n  <book category=\"children\">\n    <title lang=\"en\">Harry Potter</title>\n    <author>J.K. Rowling</author>\n    <year>2005</year>\n    <price>29.99</price>\n  </book>\n</bookstore>`;\n\n// 1. Validate XML\nconst validationResult = XMLValidator.validate(xmlData);\nif (validationResult === true) {\n  console.log('XML is syntactically valid.');\n} else {\n  console.error('XML validation failed:', validationResult);\n  // In a real application, you might throw or exit here.\n}\n\n// 2. Parse XML to a JavaScript object\nconst parserOptions = {\n  ignoreAttributes: false, // Keep attributes\n  attributeNamePrefix: \"@_\", // Prefix for attributes\n  allowBooleanAttributes: true, // Handle boolean attributes like <tag checked/>\n  parseTagValue: true, // Attempt to parse values as numbers/booleans\n  parseAttributeValue: true, // Attempt to parse attribute values\n  trimValues: true, // Trim whitespace from values\n  cdataPropName: \"cdata\" // Name for CDATA section property\n};\nconst parser = new XMLParser(parserOptions);\n\nconst jsonObj = parser.parse(xmlData);\nconsole.log('Parsed JSON object:\\n', JSON.stringify(jsonObj, null, 2));\n\n// Example of accessing parsed data\nconsole.log('\\nFirst book title:', jsonObj.bookstore.book[0].title['#text']);\nconsole.log('Second book author:', jsonObj.bookstore.book[1].author);","lang":"typescript","description":"Demonstrates how to validate an XML string and then parse it into a JavaScript object using common configuration options, and how to access the parsed data."},"warnings":[{"fix":"Install `fast-xml-builder` separately (`npm install fast-xml-builder`) and import `XMLBuilder` from its dedicated package: `import XMLBuilder from 'fast-xml-builder';`","message":"The `XMLBuilder` class was removed from `fast-xml-parser` and moved to a separate package, `fast-xml-builder`. Directly importing or using `XMLBuilder` from `fast-xml-parser` in versions `>=5.4.0` will result in a `TypeError` or `ReferenceError`.","severity":"breaking","affected_versions":">=5.4.0"},{"fix":"Review and update XML documents or parsing configurations related to entity handling, ensuring compliance with the `@nodable/entities` v2.1.0 documentation. Adjust any logic that relies on specific entity error message strings.","message":"Version `5.7.1` introduced breaking changes in XML entity processing due to an upgrade of `@nodable/entities`. Specifically, single entity scans prevent entity values from forming other entity names, numeric external entities are no longer allowed, and entity error messages may have changed.","severity":"breaking","affected_versions":">=5.7.1"},{"fix":"Update any error handling or logging logic that specifically checks for previous entity-related error message strings to reflect the new messages.","message":"In `v5.6.0`, when `@nodable/entities` was integrated, error messages for entity-related issues were changed. While not affecting API calls, any code relying on specific error message strings for entities might break.","severity":"breaking","affected_versions":">=5.6.0"},{"fix":"If legitimate XML data frequently exceeds default entity limits, configure `XMLParser` options explicitly with higher values for `maxEntitySize`, `maxExpansionDepth`, `maxTotalExpansions`, or `maxExpandedLength` during instantiation (e.g., `new XMLParser({ maxTotalExpansions: Infinity });`).","message":"To prevent denial-of-service attacks, `fast-xml-parser` enforces default limits on XML entity expansion (e.g., `maxEntitySize`, `maxExpansionDepth`). Parsing large or complex XML documents with extensive entity use might fail with an 'entity expansion limit crossed' error.","severity":"gotcha","affected_versions":">=5.x"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Install `fast-xml-builder` separately (`npm install fast-xml-builder`) and import `XMLBuilder` from its dedicated package: `import XMLBuilder from 'fast-xml-builder';`","cause":"Attempting to instantiate `XMLBuilder` directly from `fast-xml-parser` after `v5.4.0`.","error":"TypeError: XMLBuilder is not a constructor"},{"fix":"Instantiate `XMLParser` with increased entity expansion limits in its options object, for example: `new XMLParser({ maxTotalExpansions: Infinity, maxEntitySize: 50000 });`","cause":"The parsed XML document contains a large number of entities or deeply nested entity expansions, exceeding the default security limits set by the parser.","error":"Error: Entity expansion limit crossed."},{"fix":"For CommonJS environments, use object destructuring: `const { XMLParser } = require('fast-xml-parser');`","cause":"Incorrect CommonJS import syntax for named exports. `XMLParser` is a named export.","error":"ReferenceError: XMLParser is not defined (when using CommonJS require)"},{"fix":"Explicitly configure the `XMLParser` options during instantiation to control attribute handling, value parsing, and other structural aspects. For example, `new XMLParser({ ignoreAttributes: false, attributeNamePrefix: '@_', parseAttributeValue: true });`","cause":"Default `XMLParser` options (such as `ignoreAttributes`, `attributeNamePrefix`, `parseAttributeValue`) might not align with the desired output structure, leading to unexpected JSON results.","error":"XML output structure is not as expected (e.g., attributes missing, prefixed, or values not parsed)"}],"ecosystem":"npm"}