sf-decomposer


A Salesforce CLI plugin that decomposes large metadata XML files into smaller, version-control–friendly files (XML, JSON, YAML, TOML, JSON5, or INI), and recomposes them back into deployment-ready metadata.

Table of Contents

- Quick Start
- Why sf-decomposer?
- Commands
- sf decomposer decompose
- sf decomposer recompose
- Decompose Strategies
- Custom Labels
- Permission Sets (grouped-by-tag)
- Loyalty Program Setup
- Supported Metadata
- Exceptions
- Troubleshooting
- Hooks
- Ignore Files
- .forceignore
- .sfdecomposerignore
- .gitignore
- Issues
- Built With
- Contributing
- License

---

Quick Start

1. Install the plugin

``bash
sf plugins install sf-decomposer@x.y.z
`

2. Retrieve metadata into your Salesforce DX project (e.g. sf project retrieve start).

3. Decompose the metadata types you need:

`bash
sf decomposer decompose -m "flow" -m "labels" --postpurge
`

4. Add decomposed paths to .forceignore
This is required so the Salesforce CLI does not treat decomposed files as source. Use the sample .forceignore and adjust extensions for your chosen format (.xml, .json, .yaml, etc.).

5. Commit the decomposed files to version control.

6. Before deploy, recompose and then deploy:

`bash
sf decomposer recompose -m "flow" -m "labels"
sf project deploy start
`

---

Why sf-decomposer?

Salesforce’s built-in decomposition is limited. sf-decomposer gives admins and developers more control, flexibility, and better versioning.

$3

- Broader metadata support – Works with most Metadata API types, not just the subset Salesforce decomposes.
- Selective decomposition – Decompose only what you need; use .sfdecomposerignore to skip specific files.
- Two strategies:
- unique-id (default): one file per nested element, named by content or hash.
- grouped-by-tag: one file per tag (e.g. all fieldPermissions in a permission set in fieldPermissions.xml). Use --decompose-nested-permissions for deeper permission-set decomposition.
- Full decomposition – Fully decompose types that Salesforce only partially supports (e.g. permission sets).
- Stable ordering – Elements are sorted consistently to reduce noisy diffs.
_Note: TOML and INI output may sort differently from other formats._
- Multiple formats – Output as XML, JSON, JSON5, TOML, INI, or YAML.
- CI/CD hooks – Auto decompose after retrieve and recompose before deploy via .sfdecomposer.config.json.
- Better reviews – Smaller, structured files mean clearer pull requests and fewer merge conflicts.

---

Commands

| Command | Description |
| ------------------------- | --------------------------------------------------------------- |
| sf decomposer decompose | Decompose metadata in package directories into smaller files. |
| sf decomposer recompose | Recompose decomposed files back into deployment-ready metadata. |

$3

Decomposes metadata in all local package directories (from sfdx-project.json) into smaller files.

`
USAGE
$ sf decomposer decompose -m -f -i -s [--prepurge --postpurge --debug -p --json]

FLAGS
-m, --metadata-type= Metadata suffix to process (e.g. flow, labels). Repeatable.
-f, --format= Output format: xml | yaml | json | toml | ini | json5 [default: xml]
-i, --ignore-package-directory= Package directory to skip (as in sfdx-project.json). Repeatable.
-s, --strategy= unique-id | grouped-by-tag [default: unique-id]
--prepurge Remove existing decomposed files before decomposing [default: false]
--postpurge Remove original metadata files after decomposing [default: false]
--debug Write debug log to disassemble.log [default: false]
-p, --decompose-nested-permissions With grouped-by-tag, further decompose permission set object/field permissions

GLOBAL FLAGS
--json Output as JSON.
`

Examples

`bash


Decompose flows (XML), purge before/after, with debug log

sf decomposer decompose -m "flow" -f "xml" --prepurge --postpurge --debug

Decompose flows and labels in YAML

sf decomposer decompose -m "flow" -m "labels" -f "yaml" --prepurge --postpurge --debug

Decompose flows, excluding the force-app package

sf decomposer decompose -m "flow" -i "force-app"
`

$3

Recomposes decomposed files into deployment-compatible metadata.

`
USAGE
$ sf decomposer recompose -m -i [--postpurge --debug --json]

FLAGS
-m, --metadata-type= Metadata suffix to process (e.g. flow, labels). Repeatable.
-i, --ignore-package-directory= Package directory to skip. Repeatable.
--postpurge Remove decomposed files after recomposing [default: false]
--debug Write debug log to disassemble.log [default: false]

GLOBAL FLAGS
--json Output as JSON.
`

Examples

`bash
sf decomposer recompose -m "flow" --postpurge --debug
sf decomposer recompose -m "flow" -i "force-app"
`

---

Decompose Strategies

> Important: Use one strategy per metadata type. To switch from unique-id to grouped-by-tag, run decompose with --prepurge and -s "grouped-by-tag" to regenerate.

- unique-id (default): Each nested element goes to its own file, named by unique-id fields or content hash. Leaf elements stay in a file named like the original XML.
- grouped-by-tag: All elements with the same tag (e.g. ) go into one file named after the tag (e.g. fieldPermissions.xml). Leaf elements are still grouped in the original-named file.

Permission set – unique-id

| Format | Example |
| ------ | ----------------------------------------------------------------------------------------------------------- |
| XML | !XML |
| YAML | !YAML |
| JSON | !JSON |
| JSON5 | !JSON5 |
| TOML | !TOML |
| INI | !INI |

Permission set – grouped-by-tag

| Format | Example |
| ------ | ---------------------------------------------------------------------------------------------------------------- |
| XML | !XML |
| YAML | !YAML |
| JSON | !JSON |
| JSON5 | !JSON5 |
| TOML | !TOML |
| INI | !INI |

$3

Custom labels use only the unique-id strategy. If you pass grouped-by-tag, the plugin overrides to unique-id and continues (with a warning). Each label is written to its own file.

!Decomposed Custom Labels

$3

With grouped-by-tag, use --decompose-nested-permissions (-p) to:

- Write each to its own file under objectPermissions/.
- Group by object under fieldPermissions/.

Similar to Salesforce’s decomposePermissionSetBeta2, with more control and format options.

`bash
sf decomposer decompose -m "permissionset" -s "grouped-by-tag" -p
`

!Decomposed Perm Set

$3

loyaltyProgramSetup supports only unique-id. With grouped-by-tag, the plugin overrides to unique-id and warns.

Under unique-id:

- Each element → its own file.
- Each and child → its own file.

> Recomposition for loyalty program setup removes decomposed files even without --postpurge. Use version control or CI to keep them if needed.

!Decomposed Loyalty Program Setup

---

Supported Metadata

All parent metadata types from this plugin’s version of @salesforce/source-deploy-retrieve (SDR) are supported, except where noted below.

Use the metadata suffix for -m / --metadata-type, as in SDR’s metadataRegistry.json, or infer from the file name: *.{suffix}-meta.xml.

| Metadata Type | CLI value |
| --------------------------- | -------------------------- |
| Custom Labels | labels |
| Workflows | workflow |
| Profiles | profile |
| Permission Sets | permissionset |
| AI Scoring Model Definition | aiScoringModelDefinition |
| Decision Matrix Definition | decisionMatrixDefinition |
| Bot | bot |
| Marketing App Extension | marketingappextension |

$3

| Situation | Message |
| ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| botVersion used directly | botVersion suffix should not be used. Please use bot to decompose/recompose bot and bot version files. |
| Custom Objects | Custom Objects are not supported by this plugin. |
| Unsupported SDR strategies (e.g. matchingContentFile, digitalExperience, mixedContent, bundle) | Metadata types with [matchingContentFile, digitalExperience, mixedContent, bundle] strategies are not supported by this plugin. |
| Child types (e.g. custom fields) or invalid suffix | Metadata type not found for the given suffix: field. |

---

Troubleshooting

$3

The plugin looks for sfdx-project.json from the current directory up to the drive root. If it’s not found:

`
Error (1): sfdx-project.json not found in any parent directory.
`

$3

The plugin always writes a disassemble.log (via the xml-disassembler dependency). By default it contains only errors; the CLI still processes other files.

Example terminal warning:

`
Warning: ...\Get_Info.actionCalls-meta.xml was unable to be parsed and will not be processed. Confirm formatting and try again.
`

$3

Use --debug with decompose or recompose to log detailed activity (including processed files) to disassemble.log.

$3

If a metadata file has only leaf elements (primitives, no nested structure), there is nothing to decompose. The file is skipped with a warning:

`
Warning: The XML file ...\view_of_projects_tab_on_opportunity.permissionset-meta.xml only has leaf elements. This file will not be disassembled.
`

---

Hooks

> Configure .forceignore so the Salesforce CLI ignores decomposed files; otherwise sf commands can fail.

Put .sfdecomposer.config.json in the project root to run:

- After sf project retrieve start: decompose.
- Before sf project deploy start / sf project deploy validate: recompose.

Copy and customize the sample config.

| Option | Required | Description |
| ---------------------------- | -------- | --------------------------------------------------------------------------------------------- |
| metadataSuffixes | Yes | Comma-separated metadata suffixes to decompose/recompose. |
| ignorePackageDirectories | No | Comma-separated package directories to skip. |
| prePurge | No | Remove existing decomposed files before decomposing (default: false). |
| postPurge | No | After decompose: remove originals; after recompose: remove decomposed files (default: false). |
| decomposedFormat | No | xml \| json \| json5 \| toml \| ini \| yaml (default: xml). |
| strategy | No | unique-id \| grouped-by-tag (default: unique-id). |
| decomposeNestedPermissions | No | With grouped-by-tag, set true to further decompose permission set object/field permissions. |

---

Ignore Files

$3

The Salesforce CLI must ignore decomposed files and allow recomposed files. Use the sample .forceignore and set patterns for the extensions you use (.xml, .json, .yaml, etc.).

$3

Optional. In the project root, list paths/patterns to skip when decomposing (same syntax as .gitignore 2.22.1). Ignored files are not recomposed from. With --debug, ignored matches are logged to disassemble.log.

$3

Optional. Ignore recomposed metadata and/or disassemble.log so they aren’t committed. See the sample .gitignore.

---

Issues

Bugs and feature requests: open an issue.

---

Built With

- xml-disassembler – XML disassemble/reassemble
- fs-extra – Extended Node.js fs`
- @salesforce/source-deploy-retrieve – Salesforce metadata toolkit

---

Contributing

Contributions are welcome. See CONTRIBUTING.md.

License

MIT. See LICENSE.