How to Compare package.json Files Across Branches

You open a pull request to review a dependency update, and the diff is a wall of text showing dozens of package names and versions. Manually spotting which dependencies were actually added, which versions changed, and which might conflict with other updates is tedious and error-prone. A quick side-by-side diff would save you minutes and catch the thing your team missed.

When You Need to Compare package.json Files

This comes up constantly in JavaScript and Node.js development:

• Reviewing dependency PRs— A teammate added new packages. You need to see exactly which ones, their versions, and if they're duplicated elsewhere in your monorepo.
• Auditing security updates — Your CI flagged a vulnerability. You need to trace which direct dependency brought it in and across how many package.json files it appears.
• Syncing versions in monorepos — Different apps have conflicting versions of React. Quick diff reveals the inconsistencies instantly.
• Code review efficiency — A large dependency update PR is hard to review by eye. Side-by-side diff shows exactly what changed.
• Debugging dependency conflicts — Your lockfile has conflicting versions of the same package. Compare package.json files to understand what each app actually needs.

Method 1: Using Git Diff (CLI)

The simplest approach if you already have the branches locally:

git diff main..feature-branch -- package.json

For a more detailed view showing added/removed lines with context:

git diff -U10 main..feature-branch -- package.json

Limitations:Shows raw text diff, not semantic understanding. Doesn't highlight which dependencies were added/removed. Hard to read with large package.json files (50+ dependencies).

When to use: Quick, local checks before pushing.

Method 2: GitHub Pull Request Diff

If your PR is already open on GitHub:

1. Go to the Files changed tab
2. Scroll to package.json
3. GitHub shows a side-by-side view of the changes

Limitations:Only works for already-opened PRs. Can't compare arbitrary branches or offline files.

When to use:Reviewing a PR you're about to merge.

Method 3: Online Diff Tools (Recommended)

Tools like Online Diff let you paste two package.json files and see a formatted, syntax-highlighted comparison:

1. Extract the package.json content from each branch/repo
2. Paste into an online diff tool (left side = current, right side = new)
3. Review the changes with clear visual highlighting:
   • Added dependencies (green)
   • Removed dependencies (red)
   • Modified version constraints (yellow)

Example diff output showing a version bump and new package:

"dependencies": {
  "react": "^18.2.0"        // Main
  "react": "^18.3.0"        // Feature branch (version updated)
  "lodash": "^4.17.21"
  "axios": "^1.6.0"         // New package in feature branch
}

Advantages:

• No CLI required (works anywhere)
• Clear visual highlighting and formatting
• Can save/share the comparison with colleagues
• Works offline (no data sent to servers)

When to use: Detailed code reviews, sharing diffs with non-technical stakeholders, auditing changes across multiple files.

Method 4: npm Diff (npm 8.0+)

npm 8 introduced a built-in npm diff command:

npm diff -- package.json

Limitations: Only works with installed packages. Newer npm versions may not be available in older projects.

When to use:When you're comparing installed packages and have npm 8+.

Best Practices for Comparing package.json

Compare both package.json AND package-lock.json

Version constraints in package.json can hide transitive dependency changes. The lockfile reveals the full picture. If only package.json changed, the lockfile will show all resolved versions:

git diff main..branch -- package.json package-lock.json

Watch for peer dependency mismatches

When comparing, pay special attention to peerDependencies— version conflicts here often cause silent runtime bugs that tests miss. If one package needs React 17 and another needs React 18, you'll have trouble.

Normalize formatting before comparing

Some tools will diff whitespace differences. Run npm install before comparing to ensure consistent lockfile formatting and catch actual dependency changes instead of formatting noise.

Automate for monorepos

If you have 10+ packages, use a script to extract and diff all package.json files at once:

for dir in packages/*/; do
  echo "Diffing $dir/package.json"
  git diff main..feature -- "$dir/package.json"
done

Use semantic versioning awareness

When you see ^18.2.0 → ^18.3.0, that's a minor version bump — likely safe. But ^18.2.0 → ^19.0.0 is a major version change — requires testing. A quick diff makes this obvious at a glance.

Real-World Workflow

Here's how to integrate this into your code review process:

1. Developer opens PR with dependency updates
2. CI runs security audit (npm audit)
3. Code reviewer: Copy both package.json versions into Online Diff
4. See instantly: 3 new packages (axios, zod, vitest), 1 version bump (react)
5. Check CHANGELOG for each new package
6. Approve and merge
7. After merge: Run npm install, CI tests pass

Handling Version Conflicts in Monorepos

If you manage a monorepo with multiple package.json files (e.g., apps/web/, apps/api/, packages/ui/), comparing them helps enforce consistency:

# Extract all package.json files and see version differences
git show main:apps/web/package.json > web-main.json
git show main:apps/api/package.json > api-main.json
# Then diff both in Online Diff

This prevents accidental version divergence where different apps depend on incompatible versions of the same library.

Related Guides

• Compare JSON Files Online — broader guide to JSON comparison including config files
• How to Diff YAML Files in CI/CD Pipelines — comparing configs in automated workflows
• How to Diff Docker Compose Files — service configuration comparison
• JSON Formatter — prettify or minify before comparing