Disassemble XML files into smaller, more manageable files and reassemble the XML when needed.
npm install xml-disassembler
Split large XML files into smaller, version-control–friendly pieces—then reassemble them when needed. Output as XML, INI, JSON, JSON5, TOML, or YAML.
Useful for cleaner diffs, easier collaboration, and workflows like Salesforce metadata.
> Rust implementation: For a native, high-performance alternative, see xml-disassembler-rust.
---
- Quick start
- Features
- Install
- Disassembling
- Disassembly strategies
- Reassembling
- Ignore file
- Logging
- XML parser
- Use case
- Development
- License
---
``typescript
import {
DisassembleXMLFileHandler,
ReassembleXMLFileHandler,
} from "xml-disassembler";
// Disassemble: one XML → many small files
const disassemble = new DisassembleXMLFileHandler();
await disassemble.disassemble({
filePath: "path/to/YourFile.permissionset-meta.xml",
uniqueIdElements:
"application,apexClass,name,flow,object,recordType,tab,field",
format: "json",
strategy: "unique-id",
});
// Reassemble: many small files → one XML
const reassemble = new ReassembleXMLFileHandler();
await reassemble.reassemble({
filePath: "path/to/YourFile",
fileExtension: "permissionset-meta.xml",
});
`
---
- Disassemble – Break XML into smaller components (by unique ID or by tag).
- Reassemble – Rebuild the original XML from disassembled output.
- Multiple formats – Output (and reassemble from) XML, INI, JSON, JSON5, TOML, or YAML.
- Strategies – unique-id (one file per nested element) or grouped-by-tag (one file per tag)..xmldisassemblerignore
- Ignore rules – Exclude paths via a file (same style as .gitignore).log4js
- Logging – Configurable logging via (writes to disassemble.log by default).
- Salesforce-friendly – Fits metadata and similar XML-heavy workflows.
Reassembly preserves element content and structure; element order may differ (especially with TOML).
---
`bash`
npm install xml-disassembler
---
`typescript
import { DisassembleXMLFileHandler } from "xml-disassembler";
const handler = new DisassembleXMLFileHandler();
await handler.disassemble({
filePath: "test/baselines/general",
uniqueIdElements:
"application,apexClass,name,externalDataSource,flow,object,apexPage,recordType,tab,field",
prePurge: true,
postPurge: true,
ignorePath: ".xmldisassemblerignore",
format: "json",
strategy: "unique-id",
});
`
| Option | Description |
| ------------------ | --------------------------------------------------------------------------- |
| filePath | Path to the XML file or directory to disassemble. |uniqueIdElements
| | Comma-separated element names used to derive filenames for nested elements. |prePurge
| | Remove existing disassembly output before running (default: false). |postPurge
| | Remove the source XML after disassembly (default: false). |ignorePath
| | Path to the ignore file (default: .xmldisassemblerignore). |format
| | Output format: xml, ini, json, json5, toml, yaml. |strategy
| | unique-id or grouped-by-tag. |
---
Each nested element is written to its own file, named by a unique identifier (or a SHA-256 hash if no UID is available). Leaf content stays in a file named after the original XML.
Best for fine-grained diffs and version control.
Example layouts
| Format | UID-based layout | Hash-based layout |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| XML |  |  |
| YAML |  |  |
| JSON |  |  |
| JSON5 |  |  |
| TOML |  |  |
| INI |  |  |
All nested elements with the same tag go into one file per tag. Leaf content stays in the base file named after the original XML.
Best for fewer files and quick inspection.
Example layouts
| Format | Layout |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| XML |  |
| YAML |  |
| JSON |  |
| JSON5 |  |
| TOML |  |
| INI |  |
---
`typescript
import { ReassembleXMLFileHandler } from "xml-disassembler";
const handler = new ReassembleXMLFileHandler();
await handler.reassemble({
filePath: "test/baselines/general/HR_Admin",
fileExtension: "permissionset-meta.xml",
postPurge: true,
});
`
| Option | Description |
| --------------- | --------------------------------------------------------------------------------- |
| filePath | Directory that contains the disassembled files (e.g. HR_Admin/). |fileExtension
| | Suffix for the rebuilt XML file (e.g. permissionset-meta.xml). Default: .xml. |postPurge
| | Remove disassembled files after a successful reassembly (default: false). |
---
Exclude files or directories from disassembly using an ignore file (default: .xmldisassemblerignore). Syntax matches node-ignore (similar to .gitignore).
Example:
`Skip these paths
**/secret.xml
**/generated/
---
Logging uses log4js. By default, logs go to disassemble.log at error level.
`typescript
import { setLogLevel } from "xml-disassembler";
setLogLevel("debug"); // Verbose logging
`
---
Parsing is done with fast-xml-parser, with support for:
- CDATA – "!CDATA["
- Comments –
- Attributes –
---
For a Salesforce CLI integration example, see [sf-decomposer.
---
See CONTRIBUTING.md for code style, PR process, and coverage expectations.
---
This project is based on a template by Allan Oricil; the original template code is under the ISC license. The xml-disassembler code is under the MIT license.