{"id":16022,"library":"express-xml-bodyparser","title":"Express XML Body Parser Middleware","description":"express-xml-bodyparser is a Connect/Express middleware designed to parse incoming raw XML request bodies, converting them into a JavaScript object available on `req.body`. It leverages the `xml2js` library for XML parsing. The current stable version is 0.4.1. The package has a slow release cadence, with updates typically addressing dependencies or minor fixes, rather than frequent feature additions. Key differentiators include its ability to parse data only once even if called multiple times, gracefully skip parsing for empty bodies, and accept a wide range of XML-based content-types (e.g., `application/rss+xml`). It provides custom configuration options that are merged with opinionated defaults to normalize the resulting JSON structure, such as trimming whitespace and lowercasing tag names, which users need to be aware of if they desire standard `xml2js` behavior. TypeScript type definitions are available via `@types/express-xml-bodyparser`.","status":"maintenance","version":"0.4.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/macedigital/express-xml-bodyparser","tags":["javascript","xml","json","middleware","parser","express"],"install":[{"cmd":"npm install express-xml-bodyparser","lang":"bash","label":"npm"},{"cmd":"yarn add express-xml-bodyparser","lang":"bash","label":"yarn"},{"cmd":"pnpm add express-xml-bodyparser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core XML parsing engine.","package":"xml2js","optional":false}],"imports":[{"note":"While examples show CommonJS `require`, modern Node.js environments (>=18.0) can use ESM import. The package exports a default function.","wrong":"const xmlparser = require('express-xml-bodyparser').default;","symbol":"xmlparser","correct":"import xmlparser from 'express-xml-bodyparser';"},{"note":"This is the primary documented CommonJS import pattern and works in Node.js environments.","symbol":"xmlparser","correct":"const xmlparser = require('express-xml-bodyparser');"},{"note":"For type checking the middleware function or its options, you typically import `express` types and potentially `xml2js` options if extending them, as `express-xml-bodyparser` provides its own types via DefinitelyTyped.","symbol":"MiddlewareFunction","correct":"import type { Request, Response, NextFunction } from 'express';\nimport type { Options as Xml2JsOptions } from 'xml2js';"}],"quickstart":{"code":"import express from 'express';\nimport http from 'http';\nimport xmlparser from 'express-xml-bodyparser';\n\nconst app = express();\nconst server = http.createServer(app);\n\n// Apply JSON and URL-encoded body parsers first if needed\napp.use(express.json());\napp.use(express.urlencoded({ extended: true }));\n\n// Apply the XML body parser globally\napp.use(xmlparser());\n\napp.post('/receive-xml', function(req, res, next) {\n  // req.body contains the parsed XML as a JavaScript object\n  console.log('Received XML body:', req.body);\n  if (req.body) {\n    res.status(200).json({ message: 'XML received', data: req.body });\n  } else {\n    res.status(400).json({ message: 'No XML body received' });\n  }\n});\n\n// Example of using xmlparser on a specific route with custom options\napp.post('/receive-xml-custom', xmlparser({ trim: false, explicitArray: false }), function(req, res, next) {\n  console.log('Received custom XML body:', req.body);\n  if (req.body) {\n    res.status(200).json({ message: 'XML received with custom options', data: req.body });\n  } else {\n    res.status(400).json({ message: 'No XML body received' });\n  }\n});\n\nconst PORT = 1337;\nserver.listen(PORT, () => {\n  console.log(`Server listening on http://localhost:${PORT}`);\n  console.log('Send POST requests to /receive-xml or /receive-xml-custom with Content-Type: application/xml');\n});","lang":"typescript","description":"This quickstart initializes an Express application, applies the xml-bodyparser middleware globally, and sets up a route to handle incoming XML requests, demonstrating how to access the parsed `req.body` and how to apply the middleware with custom `xml2js` options on specific routes."},"warnings":[{"fix":"Review applications that use custom XML MIME types to ensure they function as expected after upgrading to v0.3.0 or later. Adjust `Content-Type` handling if necessary.","message":"Version 0.3.0 introduced a fix for a regression in handling custom MIME-type declarations. While a fix, it was noted as a 'potential breaking change for some applications' if they relied on the previous, incorrect behavior.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Avoid directly mutating `xmlparser.regexp`. If custom MIME-type detection is required, consider alternative middleware or preprocessing the request before passing it to `express-xml-bodyparser`.","message":"Mutating the `xmlparser.regexp` property (e.g., `xmlparser.regexp = /your-regex/`) is deprecated as of v0.3.0 and will be removed entirely in v1.0.0. This practice can lead to nasty side-effects.","severity":"deprecated","affected_versions":">=0.3.0"},{"fix":"Ensure `async: false` is used (which is the default) or implement rigorous XML input validation if you choose to override this default. Monitor upstream `node-xml2js` for resolutions to this issue if `async: true` is critical for your use case.","message":"Since v0.2.2, `async=false` is the default parsing mode due to upstream `node-xml2js` issues where malformed input could lead to uncaught exceptions in async mode. Using `async: true` is strongly discouraged unless you have robust input validation, as it can make your application vulnerable to crashes.","severity":"gotcha","affected_versions":">=0.2.2"},{"fix":"If you require `xml2js`'s default behavior, you must explicitly set the `express-xml-bodyparser` opinionated defaults to `false` in your options object (e.g., `{ explicitArray: false, normalize: false, normalizeTags: false }`). Update any client-side logic expecting a 411 status for empty bodies.","message":"In v0.1.0, the options merging logic changed. Custom options are now *merged* with `express-xml-bodyparser`'s opinionated defaults (e.g., `explicitArray: true`, `normalize: true`, `normalizeTags: true`, `trim: true`), instead of being merged with `xml2js`'s raw defaults. Also, an empty request body now returns a 200 status instead of 411.","severity":"breaking","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure the client sends `Content-Type: application/xml` (or another recognized XML MIME type like `application/rss+xml`). Verify that `app.use(xmlparser())` or `xmlparser()` is correctly placed before your route handler.","cause":"The `req.body` property is `undefined` because the middleware did not parse the request body. This often happens if the `Content-Type` header is not an XML type, or the `express-xml-bodyparser` middleware is not applied before the route handler.","error":"TypeError: Cannot read properties of undefined (reading 'body')"},{"fix":"Ensure `async: false` is set (which is the default behavior in recent versions) or implement robust try-catch blocks around XML parsing if you explicitly require asynchronous processing and anticipate malformed input.","cause":"This error or similar uncaught exceptions can occur when processing malformed XML input, especially if the `async: true` option is enabled, which is discouraged.","error":"UnhandledPromiseRejectionWarning: Error: Uncaught, unspecified 'error' event."},{"fix":"To override these opinionated defaults and use `xml2js`'s standard behavior, explicitly set the desired options to `false` in your configuration object, e.g., `xmlparser({ explicitArray: false, normalize: false, normalizeTags:","cause":"By default, `express-xml-bodyparser` merges your provided options with its own opinionated defaults, which include `normalize: true`, `normalizeTags: true`, `explicitArray: true`, and `trim: true`.","error":"XML body is not parsed as expected (e.g., tags not lowercased, arrays not explicit)"}],"ecosystem":"npm"}