{"id":20227146,"url":"https://github.com/imrdjai/xml-jsx-runtime","last_synced_at":"2026-05-08T05:55:57.963Z","repository":{"id":55142619,"uuid":"522902647","full_name":"iMrDJAi/xml-jsx-runtime","owner":"iMrDJAi","description":"A custom automatic JSX runtime that transforms JSX into xml-js's non-compact objects that can be converted into plain XML strings.","archived":false,"fork":false,"pushed_at":"2022-10-15T09:43:08.000Z","size":90,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-14T14:41:11.432Z","etag":null,"topics":["javascript","jsx","typescript","xml"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iMrDJAi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-08-09T10:29:34.000Z","updated_at":"2022-08-11T13:09:33.000Z","dependencies_parsed_at":"2022-08-14T13:20:26.989Z","dependency_job_id":null,"html_url":"https://github.com/iMrDJAi/xml-jsx-runtime","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iMrDJAi%2Fxml-jsx-runtime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iMrDJAi%2Fxml-jsx-runtime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iMrDJAi%2Fxml-jsx-runtime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iMrDJAi%2Fxml-jsx-runtime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iMrDJAi","download_url":"https://codeload.github.com/iMrDJAi/xml-jsx-runtime/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241670155,"owners_count":20000327,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","jsx","typescript","xml"],"created_at":"2024-11-14T07:23:06.052Z","updated_at":"2026-05-08T05:55:57.341Z","avatar_url":"https://github.com/iMrDJAi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xml-jsx-runtime\n\n[![npm](https://img.shields.io/npm/v/xml-jsx-runtime)](https://www.npmjs.com/package/xml-jsx-runtime) [![GitHub Repo stars](https://img.shields.io/github/stars/iMrDJAi/xml-jsx-runtime?style=social)](https://github.com/iMrDJAi/xml-jsx-runtime)\n\nA custom [automatic](https://babeljs.io/docs/en/babel-plugin-transform-react-jsx#react-automatic-runtime) JSX runtime that transforms JSX into [xml-js](https://github.com/nashwaan/xml-js)'s non-compact objects that can be converted into plain XML strings.\n\n***\n## Installation:\n\nInstall the runtime from npm:\n```bash\nnpm install xml-jsx-runtime -D\n```\n\nYou also need to install [xml-js](https://github.com/nashwaan/xml-js) independently in order to convert your XML non-compact objects into strings:\n\n```bash\nnpm install xml-js -S\n```\n\n## Usage:\n\n**Method 1:** with a configuration file.\n\nPass the following options to [`@babel/plugin-transform-react-jsx`](https://babeljs.io/docs/en/babel-plugin-transform-react-jsx#usage) (or whatever JSX transformer you're using):\n\n```js\n{\n  \"throwIfNamespace\": false,\n  \"runtime\": \"automatic\",\n  \"importSource\": \"xml-jsx-runtime/runtime\"\n}\n```\n\nNote that you might not be using [`@babel/plugin-transform-react-jsx`](https://www.npmjs.com/package/@babel/plugin-transform-react-jsx) directly, as it is included in other presets such as  [`@babel/preset-react`](https://www.npmjs.com/package/@babel/preset-react) or [`@vitejs/plugin-react`](https://www.npmjs.com/package/@vitejs/plugin-react). Or you might be using esbuild's own [JSX loader](https://esbuild.github.io/content-types/#jsx) instead. Either way, you should figure out how to configure your JSX loader by yourself.\n\n**Method 2:** with a `@jsxImportSource` pragma comment (recommanded).\n\nYou may add the following comment to the top of your `.jsx` file:\n\n```js\n/** @jsxImportSource xml-jsx-runtime/runtime */\n```\n\nAnd the runtime will be explicitly enabled for that file (only).\n\nThis method allows you to keep using React JSX in your project, and only use xml-jsx-runtime where you need it.\n\nYou'll still need to set `throwIfNamespace` to `false` from your configuration file if you want XML namespace support. Also you should add `/** @jsxRuntime automatic */` as well if it's not already set by default.\n\n## Examples \u0026 Features\n\nQuick start:\n\n```tsx\n/** @jsxImportSource xml-jsx-runtime/runtime */\nimport { js2xml } from 'xml-js'\n\n\nconst src = \u003cbook category='WEB'\u003e\n  \u003ctitle lang='en'\u003eLearning XML\u003c/title\u003e\n  \u003cauthor\u003eErik T. Ray\u003c/author\u003e\n  \u003cyear\u003e2003\u003c/year\u003e\n  \u003cprice\u003e39.95\u003c/price\u003e\n\u003c/book\u003e\n\nconsole.log(src)\n/** Output:\n * XMLElement {\n *   elements: [\n *     XMLElement {\n *       type: 'element',\n *       name: 'book',\n *       attributes: [Object],\n *       elements: [Array]\n *     }\n *   ]\n * }\n */\n\nconst xml = js2xml(src) // to xml string\n\nconsole.log(xml)\n/** Output:\n * \u003cbook category=\"WEB\"\u003e\u003ctitle lang=\"en\"\u003eLearning XML\u003c/title\u003e\u003cauthor\u003eErik T. Ray\u003c/author\u003e\u003cyear\u003e2003\u003c/year\u003e\u003cprice\u003e39.95\u003c/price\u003e\u003c/book\u003e\n */\n```\n\nFragments are supported:\n\n```tsx\n/** @jsxImportSource xml-jsx-runtime/runtime */\nimport { js2xml } from 'xml-js'\n\nconst xml = js2xml(\n  \u003c\u003e\n    \u003cbook id='1' /\u003e\n    \u003cbook id='2' /\u003e\n    \u003c\u003e\n      \u003cbook id='3' /\u003e\n      \u003c\u003e\n        \u003cbook id='4' /\u003e\n      \u003c/\u003e\n    \u003c/\u003e\n  \u003c/\u003e\n)\n\nconsole.log(xml)\n/** Output:\n * \u003cbook id=\"1\"/\u003e\u003cbook id=\"2\"/\u003e\u003cbook id=\"3\"/\u003e\u003cbook id=\"4\"/\u003e\n */\n```\n\nUnlike React, the `key` attribute isn't concidered special:\n\n```tsx\n/** @jsxImportSource xml-jsx-runtime/runtime */\nimport { js2xml } from 'xml-js'\n\nconst xml = js2xml(\n  \u003c\u003e\n    \u003celm key='1' /\u003e\n    \u003celm key='2' {...undefined} /\u003e\n    \u003celm {...undefined} key='3' /\u003e\n  \u003c/\u003e\n)\n\nconsole.log(xml)\n/** Output:\n * \u003celm key=\"1\"/\u003e\u003celm key=\"2\"/\u003e\u003celm key=\"3\"/\u003e\n */\n```\n\nNote that internally the 3rd element will fallback to the lagecy `createElement` function instead of the `jsx` function. Thankfully, `xml-jsx-runtime` handles that case correctly. See more about this issue [here](https://github.com/facebook/react/issues/20031).\n\nThe `children` attribute is reserved by JSX to pass child elements, however you may still specify it by adding the `$:` namespace prefix:\n\n```tsx\n/** @jsxImportSource xml-jsx-runtime/runtime */\nimport { js2xml } from 'xml-js'\n\nconst xml = js2xml(\n  \u003croom adults={2} $:children={1} /\u003e\n  /**\n   * Or\n   * \u003croom adults={2} {...{'$:children': 1}} /\u003e\n   * if you environment doesn't support XML namespaces\n   */\n)\n\nconsole.log(xml)\n/** Output:\n * \u003croom adults=\"2\" children=\"1\"/\u003e\n */\n```\n\nKeep in mind that the `$` character is not valid as an xml namespace prefix. However, JSX supports it, so I have decided to use it as a way to bypass such limitations. It will always gets ignored in the result.\n\nJSX always treat tags with capitalized names as [value-based](https://www.typescriptlang.org/docs/handbook/jsx.html#value-based-elements) elements, but you still may have capitalized elements by defining a variable then assigning a string to it:\n\n```tsx\n/** @jsxImportSource xml-jsx-runtime/runtime */\nimport { js2xml } from 'xml-js'\n\nconst Element = 'Element'\n\nconst xml = js2xml(\n  \u003cElement /\u003e\n)\n\nconsole.log(xml)\n/** Output:\n * \u003cElement /\u003e\n */\n```\n\nOr, you may completely avoid that pattren by adding the `$:` prefix 😁:\n\n```tsx\n/** @jsxImportSource xml-jsx-runtime/runtime */\nimport { js2xml } from 'xml-js'\n\nconst xml = js2xml(\n  \u003c$:Element /\u003e\n)\n\nconsole.log(xml)\n/** Output:\n * \u003cElement /\u003e\n */\n```\n\nFunction elements (value-based elements) are supported, just like in React:\n\n```tsx\n/** @jsxImportSource xml-jsx-runtime/runtime */\nimport { js2xml } from 'xml-js'\n\nconst Element = ({ attribute } : { attribute: string }) =\u003e (\n  \u003celement attribute={attribute} /\u003e\n)\n\nconst xml = js2xml(\n  \u003cElement attribute='value' /\u003e\n)\n\nconsole.log(xml)\n/** Output:\n * \u003celement attribute=\"value\"/\u003e\n */\n```\n\nFor children, the values `undefined`, `null`, `false`, `true` will be ignored in the result. Multidimensional arrays will get flattened automatically. Passing objects that are not instances of [`XMLElement`](https://github.com/iMrDJAi/xml-jsx-runtime/blob/master/src/XMLElement.ts), or types other than `string` or `number` will cause `xml-jsx-runtime` to throw an error. For attributes, all values will get converted into strings, even objects:\n\n```tsx\n/** @jsxImportSource xml-jsx-runtime/runtime */\nimport { js2xml } from 'xml-js'\n\nconst text = \u003ctext\u003eLorem {undefined} ipsum {null} dolor {false} sit {true} amet\u003c/text\u003e\n\nconst xml = js2xml(\n  \u003c\u003e\n    {text}\n    {[\u003ca /\u003e, [\u003cb /\u003e, false, 1337, [\u003cc /\u003e]], \u003cd attribute={{}} /\u003e]}\n  \u003c/\u003e\n)\n\nconsole.log(xml)\n/** Output:\n * \u003ctext\u003eLorem  ipsum  dolor  sit  amet\u003c/text\u003e\u003ca/\u003e\u003cb/\u003e1337\u003cc/\u003e\u003cd attribute=\"[object Object]\"/\u003e\n */\n```\n\n## License\n[MIT](https://github.com/iMrDJAi/xml-jsx-runtime/blob/master/LICENSE) © [${Mr.DJA}](https://github.com/iMrDJAi)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimrdjai%2Fxml-jsx-runtime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimrdjai%2Fxml-jsx-runtime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimrdjai%2Fxml-jsx-runtime/lists"}