fast-xml-builder

Build XML from JSON

XML Builder was part of fast-xml-parser for years. But considering that any bug in the parser may false-alarm users who are only using the builder, we have decided to split it into a separate package.

Installation

npm install fast-xml-builder

Usage

import XMLBuilder from 'fast-xml-builder';

const builder = new XMLBuilder();
const xml = builder.build({ name: 'value' });

fast-xml-builder fully supports the response generated by fast-xml-parser. You can use options like preserveOrder, ignoreAttributes, attributeNamePrefix, textNodeName, cdataPropName, commentPropName, format, indentBy, suppressEmptyNode, suppressUnpairedNode, stopNodes, oneListGroup, maxNestedTags, and many more.

Default Options

{
  attributeNamePrefix: '@_',
  attributesGroupName: false,
  textNodeName: '#text',
  ignoreAttributes: true,
  cdataPropName: false,
  commentPropName: false,
  format: false,
  indentBy: '  ',
  suppressEmptyNode: false,
  suppressUnpairedNode: true,
  suppressBooleanAttributes: true,
  preserveOrder: false,
  processEntities: true,
  unpairedTags: [],
  stopNodes: [],
  oneListGroup: false,
  maxNestedTags: 100,
  jPath: true,
  tagValueProcessor: (key, val) => val,
  attributeValueProcessor: (attrName, val) => val,
}

Options Reference

Check Options reference for more detail and examples.

• arrayNodeName: When building XML from an array, set arrayNodeName to wrap each element in a tag name.
• attributeNamePrefix: Prefix used to identify attribute properties in the JS object. Default: '@_'.
• attributesGroupName: Group name for attributes in the JS object. When set, all attributes are expected to be nested under this key. Not supported with preserveOrder: true.
• attributeValueProcessor: Customize how attribute values are serialized. Receives the attribute name and value.
• cdataPropName: Property name that identifies CDATA content. Values under this key are wrapped in <![CDATA[...]]>.
• commentPropName: Property name that identifies comment content. Values under this key are rendered as <!-- ... -->.
• format: By default, output is a single-line XML string. Set format: true for human-readable, indented output.
• ignoreAttributes: By default (true), attributes are skipped. Set to false to include them. Also supports selective ignoring via an array of strings, array of regular expressions, or a callback function.
• indentBy: String used for each level of indentation. Default: ' ' (two spaces). Only applies when format: true.
• maxNestedTags: Limits the maximum depth of nested tags. An error is thrown if this depth is exceeded. Default: 100.
• oneListGroup: Groups all repeated child tags under a single parent tag.
• preserveOrder: When a JS object was produced by XMLParser with preserveOrder: true, pass the same option to XMLBuilder to reconstruct the original XML correctly.
• processEntities: When true (default), special characters in text and attribute values are replaced with XML entities (&, <, etc.). Set to false for a performance boost when you know your content has no entities. Note: quotes in attribute values are always escaped regardless of this setting.
• stopNodes: Tags listed here are treated as raw content containers — their text content is written as-is without entity encoding. Accepts an array of tag name strings or Expression instances from path-expression-matcher. The old *.tagName wildcard syntax is still accepted and automatically converted to the equivalent ..tagName deep-wildcard syntax.
• suppressBooleanAttributes: When true (default), attributes with the value true are rendered without the value (e.g. <tag attr> instead of <tag attr="true">).
• suppressEmptyNode: When true, tags with no text value are rendered as self-closing (<tag/>).
• suppressUnpairedNode: When true (default), unpaired tags are rendered without a closing slash (<br>). When false, they are rendered as <br/>.
• tagValueProcessor: Customize how tag text values are serialized. Receives the tag name and value.
• textNodeName: Property name representing the text content of a tag in the JS object. Default: '#text'.
• unpairedTags: List of tag names that have no matching closing tag (e.g. <br> in HTML).