Hidden Journey Behind virtual-react-json-diff

#json #react #webdev #typescript

The Tool I Needed Didn't Exist (And Why I Had to Build It)

Like most of you, I was working on an enterprise-level React/TypeScript project when my client requested a feature that sounded very simple:

"We need to compare two database JSON objects on screen and visualize the differences."

At first glance I thought, "Easy." I would just do a quick search on GitHub or NPM, choose a component library that handles comparison and visualization, and done.

However, after hours of searching, testing demos, and scrolling through issue trackers, I slowly realized an uncomfortable truth.

The tool I needed simply did not exist.

This story is about a huge data comparison challenge, a tight deadline, and how I ended up building the solution myself, resulting in the virtual-react-json-diff NPM package.

Chapter One: The Confidential Project That Started It All

I can't share details about the client project, but the requirement was clear: Compare two versions of database objects from different system states.

The catch? The scale. These are not small config files. These were massive objects. Sometimes a hundred rows, sometimes hundreds of thousands of nested items. When expanded as JSON, we were looking at millions of lines.

The client wanted a clean JSON diff viewer. No specific UI constraints, but it had to be fast.

Chapter Two: Hitting the Wall with Existing Solutions

I started testing every package that came close to "JSON diffing." The results were consistently disappointing:

1. UI and UX Limitations

Most existing components designed for small config files (100-200 lines). They lacked visual hierarchy, navigation aids, or scalable structures for massive datasets.

2. Performance Collapse

Almost none of them could handle large structures. Anything above a few thousand lines caused the interface to freeze or the browser to crash entirely.

3. The Contenders (and why they failed)

react-diff-viewer: Works nicely for small, line based diffs (like Git changes). But for structured JSON? It collapses instantly under the weight of nested objects.
jsondiffpatch: An amazing algorithm under the hood, but the default UI feels extremely dense with very little visual guidance. It was unusable for non-technical users viewing large datasets.
json-diff-kit: This was the turning point. The underlying algorithm was very strong, especially for nested objects. However, the UI was based on HTML Tables.

The Problem with Tables: HTML tables are notoriously difficult to virtualize effectively. When you throw 100,000 rows into a table, the DOM size explodes, and the browser dies.

Chapter Three: The Pivot and an Open Source Contribution

I realized json-diff-kit had the most accurate comparison logic. The creator had developed a solid algorithm that offered several comparison methods.

I made a decision: I would use json-diff-kit for the core logic but completely rewrite the rendering layer.

The Array Key Problem (Fixing the Core Logic)

Then came a critical edge case: comparing arrays of objects. Without a unique key (id), a standard diff algorithm compares by index. If an item is deleted from the middle, the entire diff becomes a mess of "changes" rather than a single deletion.

For an example you can see the issue

I needed to compare arrays based on a specific key (e.g., oid or id). Since no package offered this, I implemented it inside json-diff-kit and sent a Pull Request.

The maintainer reviewed and merged it quickly. This became my first serious open-source contribution.

The key-based comparison is now available via the compare-key method:

const differ = new Differ({
  arrayDiffMethod: "compare-key",
  compareKey: "userId", // or "id", "oid", etc.
  detectCircular: true,
  maxDepth: 20,
});

This allows accurate diffing of arrays where items can be added, removed, or reordered, rather than naive index-based comparison.

What's Next? Going Beyond "Good Enough"

My client was happy. The requirements were met:
✅ No freezing.
✅ Millions of rows rendered (internally).
✅ Key-based array comparison.

But I realized that if I struggled this much to find a tool, others probably were too. I wanted to create a component that wasn't just "good enough" for my client, but useful for the community.

The biggest challenge remained: How do you replace a rigid HTML Table with a fluid, high-performance, and virtualized component that can handle expanding and collapsing a tree of potentially millions of nodes without breaking?

That technical deep dive is in the next article.

=> Continue to the Deep Dive: Virtualizing Millions of JSON Lines at 60 FPS: The Technical Breakdown

See the demo and the code
GitHub
Virtual-React-Json-Diff Demo
npm