Registry / serialization / fast-xml-parser

fast-xml-parser

JSON →
library5.7.1jsnpmunverified

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.

npm install fast-xml-parser
INSTALL
IMPORT
SIG · FAST-XML-PARSER
F
fast-xml-parser
serializationjavascriptv5.7.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

XMLParser
✓ import { XMLParser } from 'fast-xml-parser';
✗ const XMLParser = require('fast-xml-parser');
The primary class for parsing XML. Ensure named import for ESM; CommonJS needs object destructuring from `require()`.
XMLValidator
✓ import { XMLValidator } from 'fast-xml-parser';
✗ import XMLValidator from 'fast-xml-parser';
Provides static methods for XML syntax validation. It is a named export, not a default export.
IXMLOptions
✓ import type { IXMLOptions } from 'fast-xml-parser';
TypeScript type definition for configuring the XMLParser instance.

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.

import { XMLParser, XMLValidator } from 'fast-xml-parser'; const xmlData = `<?xml version="1.0" encoding="UTF-8"?> <bookstore> <book category="cooking"> <title lang="en">Everyday Italian</title> <author>Giada De Laurentiis</author> <year>2005</year> <price>30.00</price> </book> <book category="children"> <title lang="en">Harry Potter</title> <author>J.K. Rowling</author> <year>2005</year> <price>29.99</price> </book> </bookstore>`; // 1. Validate XML const validationResult = XMLValidator.validate(xmlData); if (validationResult === true) { console.log('XML is syntactically valid.'); } else { console.error('XML validation failed:', validationResult); // In a real application, you might throw or exit here. } // 2. Parse XML to a JavaScript object const parserOptions = { ignoreAttributes: false, // Keep attributes attributeNamePrefix: "@_", // Prefix for attributes allowBooleanAttributes: true, // Handle boolean attributes like <tag checked/> parseTagValue: true, // Attempt to parse values as numbers/booleans parseAttributeValue: true, // Attempt to parse attribute values trimValues: true, // Trim whitespace from values cdataPropName: "cdata" // Name for CDATA section property }; const parser = new XMLParser(parserOptions); const jsonObj = parser.parse(xmlData); console.log('Parsed JSON object:\n', JSON.stringify(jsonObj, null, 2)); // Example of accessing parsed data console.log('\nFirst book title:', jsonObj.bookstore.book[0].title['#text']); console.log('Second book author:', jsonObj.bookstore.book[1].author);
Debug
Known issues
breakingThe `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`.
fix
Install `fast-xml-builder` separately (`npm install fast-xml-builder`) and import `XMLBuilder` from its dedicated package: `import XMLBuilder from 'fast-xml-builder';`
affects: >=5.4.0
breakingVersion `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.
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.
affects: >=5.7.1
breakingIn `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.
fix
Update any error handling or logging logic that specifically checks for previous entity-related error message strings to reflect the new messages.
affects: >=5.6.0
gotchaTo 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.
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 });`).
affects: >=5.x
Errors
Common errors & fixes
TypeError: XMLBuilder is not a constructor
Attempting to instantiate `XMLBuilder` directly from `fast-xml-parser` after `v5.4.0`.
fix
Install `fast-xml-builder` separately (`npm install fast-xml-builder`) and import `XMLBuilder` from its dedicated package: `import XMLBuilder from 'fast-xml-builder';`
Error: Entity expansion limit crossed.
The parsed XML document contains a large number of entities or deeply nested entity expansions, exceeding the default security limits set by the parser.
fix
Instantiate `XMLParser` with increased entity expansion limits in its options object, for example: `new XMLParser({ maxTotalExpansions: Infinity, maxEntitySize: 50000 });`
ReferenceError: XMLParser is not defined (when using CommonJS require)
Incorrect CommonJS import syntax for named exports. `XMLParser` is a named export.
fix
For CommonJS environments, use object destructuring: `const { XMLParser } = require('fast-xml-parser');`
XML output structure is not as expected (e.g., attributes missing, prefixed, or values not parsed)
Default `XMLParser` options (such as `ignoreAttributes`, `attributeNamePrefix`, `parseAttributeValue`) might not align with the desired output structure, leading to unexpected JSON results.
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 });`
Upgrade
Version history
5.7.1latest on npm
Audit
Dependencies
@nodable/entitiesrequiredHandles XML entity processing and expansion, integrated since v5.6.0.
Agent activity
6 hits · last 30 days
node
6
Resources
fast-xml-parser — npm install fast-xml-parser · libregistry