FlowDelta

Stop reviewing Salesforce Flow changes as raw XML. FlowDelta parses two versions of a .flow-meta.xml, diffs them by stable node name, and renders a self-contained interactive HTML artifact (plus diff.json) that shows added / deleted / modified / unchanged nodes and edges with per-property deltas.

Inspired by Google's Flow Lens, with a focus on CI review workflows for GitLab merge requests and GitHub pull requests. We also opted for our own HTML output over plantuml, graphviz, or mermaid.

Raw XML isn't just a Flow problem. The package also ships FlexiPageDelta, a sibling tool that does the same for .flexipage-meta.xml — semantic diffs of regions, components, and facets, rendered as an interactive outline with an optional template-aware wireframe canvas so you can see where on the page layout changed, not just what. flexipage-delta, flexipage-delta-gitlab, and flexipage-delta-github ship alongside the Flow binaries.

• Sample GitLab project with artifacts
• Sample GitHub project with artifacts

Quick Start

No install required:

npx @syntax-syllogism/flow-delta --old before.flow-meta.xml --new after.flow-meta.xml --out ./flow-delta-out

Open the generated .html file in a browser to see the interactive diff shown above.

Prefer a permanent install?

npm install -g @syntax-syllogism/flow-delta
flow-delta --old before.flow-meta.xml --new after.flow-meta.xml --out ./flow-delta-out

Working with Lightning pages instead? FlexiPageDelta is available too:

npx flexipage-delta --old before.flexipage-meta.xml --new after.flexipage-meta.xml --out ./flexipage-delta-out

Usage

See docs/cli.md for full file-mode and git-mode options.

For FlexiPage metadata, see docs/flexipage.md for the full CLI, outline/wireframe artifact, and CI reporting details:

npx flexipage-delta --old before.flexipage-meta.xml --new after.flexipage-meta.xml --out ./flexipage-delta-out --json

# File mode — compare two local files
npx @syntax-syllogism/flow-delta --old before.flow-meta.xml --new after.flow-meta.xml --out ./flow-delta-out --json

# Git mode — compare two refs in a repo
npx @syntax-syllogism/flow-delta --repo /path/to/sfdx-repo --from main --to feature-branch --path 'force-app/**/*.flow-meta.xml' --out ./flow-delta-out

CI reporters read the generated flow-delta-out/*.diff.json files and post a sticky review comment. Install the package first (these binaries don't map 1:1 to the package name, so plain npx won't resolve them):

npm install @syntax-syllogism/flow-delta
npx flow-delta-gitlab --in flow-delta-out
npx flow-delta-github --in flow-delta-out

FlexiPageDelta has the same reporters — swap in flexipage-delta-gitlab / flexipage-delta-github and point --in at flexipage-delta-out.

The GitHub reporter can also consume --artifact-urls <manifest.json> for user-owned live-render links, such as R2 presigned URLs or Cloudflare Worker-backed URLs. See docs/ci.md for GitLab/GitHub workflow recipes, private-repo artifact viewing, and smoke harnesses.

Development

Working from a clone of this repo? Runs as a TypeScript CLI via tsx, no build step:

npm install
npm test                 # parser + semantic diff / render / CLI suites
npm run render:fixtures  # render all Flow + FlexiPage fixtures
npm run render:fixtures -- flow       # Flow only
npm run render:fixtures -- flexipage  # FlexiPage only
npx tsx src/cli.ts --old before.flow-meta.xml --new after.flow-meta.xml --out ./flow-delta-out --json

Architecture, testing, and the vendored-parser policy are documented in docs/ (start with docs/architecture.md).

Contributing

See CONTRIBUTING.md and the Code of Conduct.

Security

See SECURITY.md for how to report vulnerabilities.

License

MIT © Jacob Richter — applies to FlowDelta-authored code.

FlowDelta also vendors the Flow parser (src/parser/) from Google's Flow Lens (google-flow-lens), which is licensed under the Apache License 2.0. Those files retain their original headers; see NOTICE for attribution and provenance, and docs/vendoring.md for the policy.