fastify-xml-body-parser

Fastify plugin to parse XML request bodies into JavaScript objects. Powered by @nodable/flexible-xml-parser.

Installation

npm install fastify-xml-body-parser

Quick Start

const fastify = require('fastify')();
const xmlBodyParser = require('fastify-xml-body-parser');

fastify.register(xmlBodyParser);

fastify.post('/api', (req, res) => {
  console.log(req.body); // parsed JS object
  res.send(req.body);
});

fastify.listen({ port: 3000 });

Send a request:

curl -X POST http://localhost:3000/api \
  -H 'Content-Type: application/xml' \
  -d '<book><title>1984</title><year>1949</year></book>'
# → { book: { title: '1984', year: 1949 } }

Options

All options are passed directly to @nodable/flexible-xml-parser. The only plugin-specific option is contentType.

contentType

Content-type string or array of strings to register the parser for.

Default: ['text/xml', 'application/xml', 'application/rss+xml']

// Single content type
fastify.register(xmlBodyParser, { contentType: 'application/atom+xml' });

// Multiple content types
fastify.register(xmlBodyParser, {
  contentType: ['text/xml', 'application/xml', 'my/xml'],
});

Parser Options (from @nodable/flexible-xml-parser)

Any additional options are forwarded to the parser. The plugin sets HTTP-appropriate defaults that differ from the library's own defaults:

| Option | Plugin default | Description | |---|---|---| | skip.attributes | false | Attributes are parsed — common in XML APIs and SOAP/RSS | | skip.nsPrefix | false | Set to true to strip namespace prefixes | | attributes.prefix | '@_' | Prefix for attribute keys | | limits.maxNestedTags | 100 | Rejects deeply nested payloads (DoS guard) | | limits.maxAttributesPerTag | 50 | Rejects attribute-flood payloads (DoS guard) | | doctypeOptions.enabled | false | DOCTYPE entity expansion disabled (safe default) |

User-supplied limits and skip are merged with these defaults, so you only need to specify what you want to change.

Opt out of attribute parsing

fastify.register(xmlBodyParser, {
  skip: { attributes: true },
});

Strip namespace prefixes

fastify.register(xmlBodyParser, {
  skip: { nsPrefix: true },
});
// <soap:Envelope><soap:Body>hello</soap:Body></soap:Envelope>
// → { Envelope: { Body: 'hello' } }

Security: protect against malicious input

For public-facing endpoints, set structural limits:

fastify.register(xmlBodyParser, {
  limits: {
    maxNestedTags: 50,
    maxAttributesPerTag: 20,
  },
  doctypeOptions: { enabled: false }, // default — never expand DOCTYPE from untrusted input
});

Malformed or limit-exceeding XML is automatically rejected with a 400 Bad Request response.

Error Handling

Parse errors are returned as 400 Bad Request with a JSON body:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid Format: <description>"
}

All other unexpected errors propagate to Fastify's standard error handler.

Migration from v2

v3 drops fast-xml-parser in favour of @nodable/flexible-xml-parser. The API surface is similar but there are breaking changes:

| v2 | v3 | |---|---| | validate: true | Removed — parse errors always throw ParseError and return 400 | | removeNSPrefix: true | skip: { nsPrefix: true } | | ignoreAttributes: false | skip: { attributes: false } | | attributeNamePrefix | attributes.prefix | | fastify-plugin v3 | fastify-plugin v5 | | Fastify >=3 | Fastify >=4 |

License

MIT — Amit Gupta