xast-util-to-xml

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require()` to import `xast-util-to-xml` in an ESM environment.
  fix Change `const toXml = require('xast-util-to-xml')` to `import { toXml } from 'xast-util-to-xml'`.

• ERR_PACKAGE_PATH_NOT_EXPORTED

  cause Attempting to import a non-exported module path, often a consequence of the `exports` map in `package.json` since v4.0.0.
  fix Ensure you are importing `toXml` directly from the package's root: `import { toXml } from 'xast-util-to-xml'` and not from any internal paths like `xast-util-to-xml/lib/index.js`.

• Error: Cannot find module 'xast-util-to-xml'

  cause Running a project with xast-util-to-xml v4.0.0 or higher on an unsupported Node.js version (e.g., Node.js 14).
  fix Upgrade your Node.js runtime to version 16 or newer. Alternatively, downgrade `xast-util-to-xml` to a 3.x release.

• TS2742: The inferred type of 'toXml' cannot be named without a reference to a UMD global. Consider adding an import of 'xast' or 'unist' to the current file, or migrating to a module-based project.

  cause TypeScript compiler is having trouble resolving types, often due to a mixed CommonJS/ESM setup or missing explicit imports for related type definitions from `xast` or `unist`.
  fix Ensure your `tsconfig.json` targets an appropriate module system (e.g., `"module": "esnext"`). Explicitly import any necessary types, e.g., `import type { Root } from 'xast'`.

Warnings

• breaking Version 4.0.0 of xast-util-to-xml requires Node.js 16 or higher. Ensure your Node.js environment meets this minimum requirement.
  Fix: Upgrade your Node.js environment to version 16 or newer, or stick to v3.x versions for older Node.js compatibility.
• breaking Since version 3.0.0, xast-util-to-xml is an ESM-only package. CommonJS `require()` statements will no longer work.
  Fix: Migrate your codebase to use ES module `import` statements. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).
• breaking Version 4.0.0 introduced the use of `exports` field in `package.json`. While this generally improves module resolution, it can break applications that relied on direct access to internal, non-exported paths.
  Fix: Ensure you are only importing publicly exported APIs (e.g., `import { toXml } from 'xast-util-to-xml'`). Avoid deep imports into subdirectories or internal modules.
• breaking Version 2.0.0 introduced official TypeScript types. If you previously maintained your own ambient type declarations for `xast-util-to-xml`, these might conflict with the shipped types.
  Fix: Remove any custom or `@types/xast-util-to-xml` declarations and rely on the types provided by the package itself. Review type errors that may arise due to stricter type checking.
• gotcha The `allowDangerousXml` option, when set to `true`, inserts `Raw` nodes directly into the output XML without escaping. This can lead to Cross-Site Scripting (XSS) vulnerabilities if the content of `Raw` nodes is untrusted.
  Fix: Only enable `allowDangerousXml` if you have complete control over and trust the content of all `Raw` nodes. For user-generated or external content, ensure proper sanitization is applied before creating `Raw` nodes or avoid this option entirely.

Install

• npm install xast-util-to-xml npm
• yarn add xast-util-to-xml yarn
• pnpm add xast-util-to-xml pnpm

Imports

• toXml
  wrong:

  const toXml = require('xast-util-to-xml')

  correct:

  import { toXml } from 'xast-util-to-xml'

  This package is ESM-only since v3.0.0. Use `import` syntax. Node.js 16+ is required for v4.0.0.
• toXml (Deno)

  import { toXml } from 'https://esm.sh/xast-util-to-xml@4'

  For Deno environments, import directly from esm.sh specifying the major version.
• Options
  wrong:

  import { Options } from 'xast-util-to-xml'

  correct:

  import type { Options } from 'xast-util-to-xml'

  Import the `Options` type using `import type` for type-only imports, especially in TypeScript projects to prevent runtime bundling issues.

Quickstart

This example demonstrates how to create an xast tree using `unist-builder` and `xastscript`, and then serialize it to an XML string using `toXml`, applying custom options.

import { u } from 'unist-builder'
import { x } from 'xastscript'
import { toXml } from 'xast-util-to-xml'

const tree = u('root', [
  u('instruction', {name: 'xml'}, 'version="1.0" encoding="utf-8"'),
  u('text', '\n'),
  x('ncx', {xmlns: 'http://www.daisy.org/z3986/2005/ncx/', version: '2005-1'}, [
    u('text', '\n  '),
    x('head', [
      u('text', '\n    '),
      x('meta', {name: 'dtb:uid', content: 'urn:isbn:9781234567891'}),
      u('text', '\n  ')
    ]),
    u('text', '\n  '),
    x('docTitle', [x('text', 'A Christmas Carol')]),
    u('text', '\n  '),
    x('docAuthor', [x('text', 'Charles Dickens')]),
    u('text', '\n')
  ])
])

const xmlOutput = toXml(tree, { closeEmptyElements: true, quote: "'" })
console.log(xmlOutput)
// Expected output:
// <?xml version='1.0' encoding='utf-8'?>
// <ncx xmlns='http://www.daisy.org/z3986/2005/ncx/' version='2005-1'>
//   <head>
//     <meta name='dtb:uid' content='urn:isbn:9781234567891'/>
//   </head>
//   <docTitle><text>A Christmas Carol</text></docTitle>
//   <docAuthor><text>Charles Dickens</text></docAuthor>
// </ncx>