XML-JS Converter

Common errors

• TypeError: xml2js is not a function

  cause Incorrectly importing `xml2js` as a default export or attempting to access it directly on a `require`'d module that expects a single 'convert' object.
  fix Ensure you are using named imports for `xml2js` (e.g., `import { xml2js } from 'xml-js';`) or importing the entire module as a namespace (e.g., `import * as convert from 'xml-js';` then calling `convert.xml2js(...)`). For CommonJS, use `const { xml2js } = require('xml-js');` or `const convert = require('xml-js');` and then `convert.xml2js(...)`.

• Output XML does not match input structure, elements are reordered or missing.

  cause Using `compact: true` mode for `xml2js` which simplifies the object structure and can lead to loss of element order or merging of same-named elements into arrays without preserving their original sequence relative to other unique elements.
  fix Always use `{ compact: false }` for both `xml2js` and `js2xml` when precise XML structure, element order, and full reversibility are critical. This will represent elements as an array of objects, preserving their sequence.

• The 'text' content of an element appears as an empty object or incorrect type.

  cause Mismatch between how text nodes are represented in 'compact' vs 'non-compact' modes. In non-compact, text is usually an object like `{ type: 'text', text: '...' }`, while in compact mode, it might be directly accessible or nested differently depending on other attributes/children.
  fix Consult the documentation for the specific structure generated by `compact: true` versus `compact: false`. When `compact: true`, text nodes are often accessed directly from the element property, or as `_text` property if it's mixed content. For non-compact mode, access the `text` property within an element of `type: 'text'`.

Warnings

• breaking Starting from v1.4.0, converting XML to JS will automatically decode the five standard XML entity codes (`&amp;`, `&lt;`, `&gt;`, `&quot;`, `&#39;`) into their respective characters (`&`, `<`, `>`, `"`, `'`). Previously, `&amp;` would remain `&amp;` unless explicitly sanitized. The `{sanitize: true}` option is also deprecated with this change.
  Fix: Review existing code that relies on encoded entities remaining encoded after XML to JS conversion. Adapt logic to handle decoded characters directly. The `{sanitize: true}` option should be removed as it has no effect.
• breaking In v1.1.0, the default behavior for CData block indentation in XML output changed. CData blocks are no longer indented by default, which may affect formatting for users who relied on the previous indented output.
  Fix: If indented CData output is required, explicitly set the `{indentCdata: true}` option when calling `js2xml`.
• gotcha When converting from a JavaScript object to XML, v1.5.1 introduced support for a simpler syntax where `{a: 'hi'}` can be converted to `<a>hi</a>` directly, instead of requiring `{a: {_text: 'hi'}}`. While this is an improvement, it changes the expected object structure for simple text nodes.
  Fix: Be aware of this change when constructing JavaScript objects for `js2xml`. Both `{a: 'hi'}` and `{a: {_text: 'hi'}}` should generally work, but the simpler form is now supported for convenience and cleaner output.
• gotcha The library offers two main modes: 'compact' and 'non-compact'. The 'non-compact' mode is recommended for preserving the exact order of elements, representing all elements as an array of objects under an 'elements' key. The 'compact' mode, while simpler, might merge elements of the same name into a single array property, losing their original ordering relative to other distinct elements.
  Fix: For precise XML structure preservation and reversibility, always use `{ compact: false }` for both `xml2js` and `js2xml`. Use `{ compact: true }` only if you understand and accept the simplified, potentially order-losing, JSON structure.

Install

• npm install xml-js npm
• yarn add xml-js yarn
• pnpm add xml-js pnpm

Imports

• xml2js
  wrong:

  const xml2js = require('xml-js').xml2js;

  correct:

  import { xml2js } from 'xml-js';
  // Or if using the unified convert object:
  // import * as convert from 'xml-js';
  // const jsObj = convert.xml2js(xmlString);

  While CommonJS `require` works, modern Node.js and browser environments typically use ES module `import`. The library can also be imported as a single 'convert' object from which `xml2js` is accessed.
• js2xml
  wrong:

  const js2xml = require('xml-js').js2xml;

  correct:

  import { js2xml } from 'xml-js';
  // Or if using the unified convert object:
  // import * as convert from 'xml-js';
  // const xmlString = convert.js2xml(jsObj);

  Similar to xml2js, js2xml can be imported directly or accessed as a method on the main 'convert' export.
• convert
  wrong:

  import convert from 'xml-js';

  correct:

  import * as convert from 'xml-js';

  The library primarily uses named exports for its functions. Importing the entire module as 'convert' with `* as` is the correct way to access `convert.xml2js` and `convert.js2xml` methods while maintaining ES module compatibility.

Quickstart

Demonstrates converting an XML string to JavaScript objects in both compact and non-compact modes, then converting these JavaScript objects back into formatted XML strings.

import { xml2js, js2xml } from 'xml-js';

// Example XML string
const xmlString = `
  <?xml version="1.0" encoding="UTF-8"?>
  <!-- Sample XML Document -->
  <bookstore>
    <book category="programming">
      <title lang="en">Learning XML</title>
      <author>John Doe</author>
      <price>39.95</price>
    </book>
    <book category="web">
      <title lang="en">HTML &amp; CSS</title>
      <author>Jane Smith</author>
      <price>29.99</price>
      <description><![CDATA[A comprehensive guide to web design.]]></description>
    </book>
  </bookstore>
`;

// 1. Convert XML to JavaScript object (non-compact, preserving order)
const jsObjectNonCompact = xml2js(xmlString, { compact: false, spaces: 2 });
console.log('--- Non-Compact JS Object ---');
console.log(JSON.stringify(jsObjectNonCompact, null, 2));

// 2. Convert XML to JavaScript object (compact mode)
const jsObjectCompact = xml2js(xmlString, { compact: true, spaces: 2 });
console.log('\n--- Compact JS Object ---');
console.log(JSON.stringify(jsObjectCompact, null, 2));

// 3. Convert JavaScript object back to XML (from compact object)
const xmlOutputFromCompact = js2xml(jsObjectCompact, { compact: true, spaces: 2 });
console.log('\n--- XML Output from Compact JS Object ---');
console.log(xmlOutputFromCompact);

// 4. Convert JavaScript object back to XML (from non-compact object)
const xmlOutputFromNonCompact = js2xml(jsObjectNonCompact, { compact: false, spaces: 2 });
console.log('\n--- XML Output from Non-Compact JS Object ---');
console.log(xmlOutputFromNonCompact);