React Monaco JSON Merge

A powerful React component for 3-way JSON merging with semantic comparison, built on Monaco Editor

🌐 Live Demo

✨ Features

Core Capabilities

• 🔀 3-Way Merge - Compare base, theirs, and ours versions side-by-side
• 🎨 Monaco Editor Integration - Powered by VS Code's Monaco Editor for a familiar editing experience
• 🧠 Semantic JSON Comparison - Uses JSON Patch (RFC 6902) for intelligent, structure-aware diffing
• 📋 Schema-Aware - Optional JSON Schema support for enhanced conflict detection and validation
• ✅ Interactive Resolution - Checkboxes for accepting/rejecting changes
• 🔀 Smart Merging - Automatically merges compatible conflicts
• ⚡ Real-time Validation - JSON validation with error highlighting
• 🎯 4-Column Mode - Optional result preview column for live merge preview
• 🎨 Theme Support - Light and dark themes (VS Code/monaco themes)
• ♿ Accessible - Keyboard navigation and screen reader support

Technical Highlights

• Zero Line-based Diffs - Uses semantic JSON comparison, ignoring formatting changes
• Array Matching by ID - Schema-aware array item matching (not just by index)
• Conflict Type Detection - Identifies SAME_CHANGE, INPUT1_ONLY, INPUT2_ONLY, and TRUE_CONFLICT
• Deep Merge Support - Automatically merges nested objects when possible
• TypeScript First - Fully typed with comprehensive type definitions

🚀 Quick Start

📺 Try the Live Demo - See the editor in action!

Installation

npm install react-monaco-json-merge

Basic Usage

import { JsonDiffMergeEditor } from 'react-monaco-json-merge';
import 'react-monaco-json-merge/dist/style.css';

function App() {
  const base = JSON.stringify({ name: "John", age: 30 }, null, 2);
  const theirs = JSON.stringify({ name: "John", age: 31, city: "NYC" }, null, 2);
  const ours = JSON.stringify({ name: "Jane", age: 30 }, null, 2);

  return (
    <JsonDiffMergeEditor
      base={base}
      original={theirs}
      modified={ours}
      showResultColumn={true}
      height="600px"
      onMergeResolve={(content, resolution) => {
        if (resolution?.isValid) {
          console.log('Merged JSON:', JSON.parse(content));
        }
      }}
    />
  );
}

📖 Documentation

Props

Prop	Type	Default	Description
base	string	""	Common ancestor JSON (stringified)
original	string	""	"Theirs" version JSON (stringified)
modified	string	""	"Ours" version JSON (stringified)
showResultColumn	boolean	false	Show merged result preview column
theme	string	"vs"	Monaco Editor theme ("vs", "vs-dark", "hc-black")
height	string | number	"100%"	Editor height
width	string | number	"100%"	Editor width
schema	JSONSchema	undefined	JSON Schema for validation and array matching
labels	object	undefined	Custom column labels
onMergeResolve	function	undefined	Callback when merge resolution changes
options	object	{}	Monaco Editor options
comparisonMode	"split" | "sequential"	"split"	How to display the comparison
baseIndex	0 | 1 | 2	1	Position of base column (0=left, 1=middle, 2=right)

Advanced Example

import { JsonDiffMergeEditor } from 'react-monaco-json-merge';
import type { JSONSchema } from 'react-monaco-json-merge';

const schema: JSONSchema = {
  type: "object",
  properties: {
    users: {
      type: "array",
      items: {
        type: "object",
        properties: {
          id: { type: "string" },
          name: { type: "string" }
        },
        required: ["id"]
      }
    }
  }
};

function AdvancedEditor() {
  return (
    <JsonDiffMergeEditor
      base={baseJSON}
      original={theirsJSON}
      modified={oursJSON}
      schema={schema}
      showResultColumn={true}
      theme="vs-dark"
      height="700px"
      labels={{
        input1: "Remote Changes",
        base: "Common Ancestor",
        input2: "Local Changes",
        result: "Merged Result"
      }}
      onMergeResolve={(content, resolution) => {
        if (resolution?.isValid) {
          // Save merged content
          saveToFile(content);
        } else {
          // Handle validation errors
          console.error('Merge has conflicts:', resolution?.conflictIssues);
        }
      }}
      options={{
        fontSize: 14,
        minimap: { enabled: false },
        lineNumbers: 'on'
      }}
    />
  );
}

🏗️ Architecture

Semantic vs Line-Based Diff

Unlike traditional diff tools that compare text line-by-line, this editor uses semantic JSON comparison:

1. Parses JSON to structured objects
2. Generates JSON Patch operations (RFC 6902)
3. Groups patches by JSON path
4. Maps to line numbers using jsonc-parser
5. Applies Monaco decorations based on JSON structure

Benefits:

• Ignores formatting changes (whitespace, key order)
• Schema-aware array matching (by ID, not index)
• Better conflict detection for nested JSON
• Highlights actual value changes, not formatting

Conflict Types

The editor identifies four conflict types:

• SAME_CHANGE - Both sides made identical changes (auto-merged)
• INPUT1_ONLY - Only "theirs" changed (can be accepted)
• INPUT2_ONLY - Only "ours" changed (can be accepted)
• TRUE_CONFLICT - Both sides changed to different values (requires resolution)

Smart Merging

When both checkboxes are selected for a TRUE_CONFLICT:

• If both values are objects: deep merge is performed
• If values are identical: uses either value
• If incompatible types: merge fails, shows warning

🛠️ Development

Prerequisites

• Node.js >= 20.19.0
• npm >= 10.0.0

Setup

# Clone the repository
git clone <repository-url>
cd react-monaco-json-merge

# Install dependencies
npm install

# Start development server
npm run dev

Available Scripts

# Development
npm run dev              # Start Vite dev server
npm run build            # Build for production
npm run preview          # Preview production build

# Code Quality
npm run type-check       # TypeScript type checking
npm run lint             # Lint code with Biome
npm run lint:fix         # Fix linting issues
npm run format           # Format code

# Testing
npm run test             # Run tests in watch mode
npm run test:run         # Run tests once
npm run test:ui          # Run tests with UI
npm run test:coverage    # Generate coverage report

# Utilities
npm run validate         # Run all checks (type-check + lint + test)
npm run clean            # Remove build artifacts

Project Structure

react-monaco-json-merge/
├── src/
│   ├── components/
│   │   └── editor.tsx          # Main JsonDiffMergeEditor component
│   ├── data/
│   │   └── sampleData.ts       # Sample data for demo
│   ├── utils/
│   │   ├── diffMerge.ts        # Merge logic
│   │   ├── jsonPatchDiff.ts    # Diff computation
│   │   ├── editorDecorations.ts # Monaco decorations
│   │   ├── helpers.ts          # Utility functions
│   │   └── schema.ts           # Schema utilities
│   ├── types/
│   │   └── index.ts            # TypeScript definitions
│   ├── styles/
│   │   └── editor.css          # Editor styles
│   ├── Demo.tsx                # Demo application
│   └── main.tsx                # Entry point
├── package.json
├── tsconfig.json
├── vite.config.ts
└── README.md

🧪 Testing

The project includes comprehensive test coverage:

• Unit Tests - Utilities and helpers (94+ tests)
• Integration Tests - Full editor rendering scenarios
• Rendering Tests - Conflict detection and highlighting
• Schema Tests - JSON Schema variant handling

Run tests with:

npm run test

View coverage report:

npm run test:coverage

📦 Dependencies

Core

• React 19 - UI framework
• Monaco Editor - Code editor
• fast-json-patch - JSON Patch (RFC 6902) implementation
• jsonc-parser - JSON with comments parsing

Utilities

• fast-deep-equal - Deep equality comparison
• sort-keys - Object key sorting

Development

• TypeScript - Type safety
• Vite - Build tool
• Vitest - Testing framework
• Biome - Linting and formatting

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Write tests for new features
• Ensure all tests pass (npm run validate)
• Follow the existing code style (enforced by Biome)
• Update documentation as needed

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Monaco Editor - The editor that powers this component
• fast-json-patch - JSON Patch implementation
• JSON Schema - Schema validation standard

📞 Support

For issues, questions, or contributions, please open an issue on GitHub.

---

Made with ❤️ for better JSON merging experiences