XML

• Parse and stringify XML with Bun.XML.parse and Bun.XML.stringify
• import & require XML files as modules at runtime (including hot reloading & watch mode support)
• import & require XML files in frontend apps with Bun’s bundler

​

Runtime API

​

Bun.XML.parse()

import { XML } from "bun";

const data = XML.parse(`
  <order id="A1" currency="USD">
    <customer>Ada</customer>
    <item sku="tea" qty="2">Green tea</item>
    <item sku="mug" qty="1">Mug</item>
    <paid/>
  </order>
`);

console.log(data);
// {
//   order: {
//     "@id": "A1",
//     "@currency": "USD",
//     customer: "Ada",
//     item: [
//       { "@sku": "tea", "@qty": "2", "#text": "Green tea" },
//       { "@sku": "mug", "@qty": "1", "#text": "Mug" },
//     ],
//     paid: "",
//   },
// }

• The result has one key, the root element’s name.
• An element with no attributes and no child elements becomes its character data: a string, "" when empty. <paid/> and <paid></paid> are the same thing in XML.
• Any other element becomes an object. It has a "@name" key per attribute, then one key per distinct child element name and a "#text" key for the element’s own text, in the order each first appears.
• When a child element name occurs more than once in the element, its key holds an array in document order. Otherwise it holds the single value. See One or many.
• compact chooses a structure; it does not change values. Bun returns text as written: leading, trailing and internal whitespace included, CDATA sections and entity references expanded, line ends normalized to \n — the same text the tree shape gives for that element. Because an element has one "#text", Bun concatenates its text runs and leaves out whitespace-only runs that sit between child elements (the document’s layout). If your documents are hand-formatted (<name>\n value\n</name>), trim where you read.
• All values are strings. Nothing is coerced to numbers, booleans, or null.
• Names are kept as written, namespace prefix included ("soap:Body"); xmlns declarations are ordinary attributes.
• Comments, processing instructions, the <?xml …?> declaration and the <!DOCTYPE …> are not represented.

XML.parse(`<p>Hello <b>world</b>!</p>`);
// { p: { "#text": "Hello !", b: "world" } }

const p = XML.parse(`<p class="lead">Hello <b>world</b>!<!-- draft --></p>`, { compact: false });

console.log(p);
// {
//   name: "p",
//   attributes: { class: "lead" },
//   children: [
//     "Hello ",
//     { name: "b", attributes: {}, children: ["world"] },
//     "!",
//     { comment: " draft " },
//   ],
// }

​

One or many

const entries = [feed.entry ?? []].flat(); // an array either way
const title = typeof e.title === "string" ? e.title : (e.title["#text"] ?? "");

​

Input types and encodings

XML.parse(await Bun.file("feed.xml").bytes());

​

Error handling

try {
  XML.parse("<a><b></a>");
} catch (error) {
  console.error(error.message); // "XML Parse error: Expected closing tag </b> but found </a>"
}

​

Bun.XML.stringify()

import { XML } from "bun";

XML.stringify({
  order: {
    "@id": "A1",
    customer: "Ada",
    item: [{ "@sku": "tea", "#text": "Green tea" }, { "@sku": "mug" }],
    paid: null,
  },
});
// '<order id="A1"><customer>Ada</customer><item sku="tea">Green tea</item><item sku="mug"/><paid/></order>'

XML.stringify({
  name: "p",
  attributes: { class: "lead" },
  children: ["Hello ", { name: "b", children: ["world"] }, "!", { comment: " draft " }],
});
// '<p class="lead">Hello <b>world</b>!<!-- draft --></p>'

await Bun.write(
  "Info.plist",
  `<?xml version="1.0" encoding="UTF-8"?>\n` +
    `<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n` +
    XML.stringify(plist, null, "\t"),
);

​

Pretty printing

console.log(XML.stringify(data, null, 2));
// <order id="A1" currency="USD">
//   <customer>Ada</customer>
//   <item sku="tea" qty="2">Green tea</item>
//   <item sku="mug" qty="1">Mug</item>
//   <paid/>
// </order>

​

Module Import

​

ES Modules

<?xml version="1.0" encoding="UTF-8"?>
<config env="production">
  <database host="localhost" port="5432" name="myapp"/>
  <feature name="auth"/>
  <feature name="rateLimit"/>
</config>

​

Default Import

app.ts

import doc from "./config.xml";

console.log(doc.config["@env"]); // "production"
console.log(doc.config.database["@host"]); // "localhost"
console.log(doc.config.feature.map(f => f["@name"])); // ["auth", "rateLimit"]

​

Named Import

app.ts

import { config } from "./config.xml";

console.log(config.database["@port"]); // "5432"

​

CommonJS

app.ts

const { config } = require("./config.xml");
console.log(config.database["@name"]); // "myapp"

​

Import Attributes

import feed from "./export.rss" with { type: "xml" };

​

Hot Reloading with XML

server.ts

import { config } from "./config.xml";

Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response(`Running in ${config["@env"]} against ${config.database["@host"]}`);
  },
});

bun --hot server.ts

​

Bundler Integration

bun build app.ts --outdir=dist

• Zero runtime XML parsing overhead in production
• Smaller bundle sizes
• Tree shaking of unused properties

​

Dynamic Imports

const { default: doc } = await import("./config.xml");

​

Conformance

• The whole document, including the internal DTD subset, must be well-formed — anything else throws a SyntaxError.
• The parser expands internal entities declared in the document, with expansion limits so “billion laughs” payloads fail instead of exhausting memory. It normalizes attribute values and applies attribute defaults declared in the internal subset.
• The parser does not fetch or read external DTDs or external entities, so there is no XXE surface. In a document with no DTD, a reference to an undeclared entity is an error. When the DOCTYPE points at an external subset (or uses parameter entities) that could have declared the entity, the parser keeps the reference as written (  stays  ), unless the document says standalone="yes".
• The parser validates nothing against the DTD. It does not resolve namespaces and keeps prefixed names verbatim.

​

Performance