@pyxy/json-diff-viewer

Framework-agnostic TypeScript library for comparing two JSON documents side by side. Ships a typed diff engine, a <json-diff-viewer> Web Component, and an imperative mount helper — with zero runtime dependencies.

Install

npm install @pyxy/json-diff-viewer

Quick start

Web Component

import '@pyxy/json-diff-viewer';

const viewer = document.querySelector('json-diff-viewer');
viewer?.setData(originalJson, updatedJson);

<json-diff-viewer before-label="before.json" after-label="after.json"></json-diff-viewer>

Imperative API

import { renderJsonDiff } from '@pyxy/json-diff-viewer';

const viewer = renderJsonDiff(document.getElementById('diff')!, {
  before: originalJson,
  after: updatedJson,
  beforeLabel: 'firstInput.json',
  afterLabel: 'secondInput.json',
  sorted: false,
});

Diff engine only

import { diffJson, sortJson } from '@pyxy/json-diff-viewer';

const sorted = sortJson(value);
const result = diffJson(before, after);

Viewer API

| Method | Description | | --- | --- | | setData(before, after) | Replace both documents and recompute | | configure(options) | Update labels, sort mode, and/or data | | nextDifference() | Focus the next change (wraps) | | previousDifference() | Focus the previous change (wraps) |

Events:

• changefocus — fired when navigation focuses a change; event.detail is the DiffChange

Features

• Aligned side-by-side rows with line numbers
• Syntax highlighting for keys, strings, numbers, booleans, and null
• Added / removed / modified highlighting
• Previous / next navigation with smooth scroll + focus pulse
• Toggle recursive alphabetical key sorting (arrays keep order)
• Changes drawer grouped by Added / Modified / Removed with JSONPath entries
• Sticky parent context bar while scrolling nested JSON
• Shadow DOM styles, accessible controls, prefers-reduced-motion support

JSONPath rules

• Root is $
• Identifier-like keys use dot notation: $.apps.Babylon
• Other keys use bracket notation: $["key-with-dashes"]
• Array entries use indexes: $.items[0]

Scripts

npm run dev      # local demo
npm test         # vitest
npm run build    # ESM + UMD + .d.ts
npm run check    # typecheck + test + build

Package exports

| Field | Path | | --- | --- | | main | dist/json-diff-viewer.umd.cjs | | module | dist/json-diff-viewer.js | | types | dist/index.d.ts |

The published library does not load external fonts or assets. The demo may load Google Fonts optionally; the component falls back to system stacks.

POC app: https://json-diff-by-tipu.netlify.app/