JSON Diff Kit

The Viewer component can be used to render the diff data produced by the Differ class. You must import the associated CSS file for the viewer to render correctly.

Viewer Props:

• diff (required): An array of DiffResult objects: [DiffResult[], DiffResult[]].
• indent (number, default: 2): Indentation level.
• lineNumbers (boolean, default: false): Whether to show line numbers.
• highlightInlineDiff (boolean, default: false): Enables inline diff highlighting.
• inlineDiffOptions (object): Configuration for inline diffing:
  • mode (string, default: "char"): Diff granularity. Use "word" for word-level diffing.
  • wordSeparator (string, default: ""): The character used to separate words (e.g., " " for sentences).

import { Viewer } from 'json-diff-kit';
import type { DiffResult } from 'json-diff-kit';
import 'json-diff-kit/dist/viewer.css';

interface PageProps {
  diff: [DiffResult[], DiffResult[]];
}

const Page: React.FC<PageProps> = props => {
  return (
    <Viewer
      diff={props.diff}
      indent={4}
      lineNumbers={true}
      highlightInlineDiff={true}
      inlineDiffOptions={{
        mode: 'word',
        wordSeparator: ' ',
      }}
    />
  );
};

To compute the difference between two JavaScript objects, instantiate the Differ class and call its .diff(before, after) method.

Configuration Options for Differ:

• detectCircular (boolean, default: true): Detects circular references.
• maxDepth (number, default: Infinity): Maximum depth to traverse.
• showModifications (boolean, default: true): Whether to show modifications.
• arrayDiffMethod (string, default: "normal"): The algorithm used for array diffing. Use "lcs" (Longest Common Subsequence) for more useful results in many cases.

import { Differ } from 'json-diff-kit';
// or if you are using vue, you can import the differ only
// import Differ from 'json-diff-kit/dist/differ';

const before = { a: 1, b: 2 };
const after = { b: 2, c: 3 };

const differ = new Differ({
  detectCircular: true,
  maxDepth: Infinity,
  showModifications: true,
  arrayDiffMethod: 'lcs',
});

const diff = differ.diff(before, after);
console.log(diff);

Use the DifferOptions interface to control the diffing algorithm's behavior.

Available Options

The hideUnchangedLines option allows you to collapse large blocks of unchanged JSON to improve readability. You can pass a boolean or a configuration object:

Configuration Object Options:

• threshold?: number - If continuous unchanged lines exceed this number, they are hidden (default: 8).
• margin?: number - Number of lines to keep visible around the expand line for context (default: 3).
• expandMoreLinesLimit?: number - How many lines are shown when clicking "Show xx lines before/after" (default: 20).
• expandLineRenderer?: (options?: ExpandLineRendererOptions) => JSX.Element - A custom renderer for the expansion line.

ExpandLineRendererOptions:

• hasLinesBefore: boolean - True if there are lines available to expand before.
• hasLinesAfter: boolean - True if there are lines available to expand after.
• onExpandBefore: (lines: number) => void - Callback to expand lines before.
• onExpandAfter: (lines: number) => void - Callback to expand lines after.
• onExpandAll: () => void - Callback to expand all lines in the segment.

The CLI tool allows you to compare two JSON files and output the diff data to the terminal or a file.

Prerequisite: You must install terminal-kit before using the CLI.

pnpm add terminal-kit

Commands:

• jsondiff run <path/to/before.json> <path/to/after.json>: Compare files and output to terminal (navigable via keyboard like less).
• jsondiff run <path/to/before.json> <path/to/after.json> -o <path/to/result.diff>: Output diff data to a file.
• jsondiff run <path/to/before.json> <path/to/after.json> -c <path/to/config.json> -o <path/to/result.diff>: Use a custom configuration file and output to a file.
• jsondiff --help or jsondiff run --help: Print help messages.

# Compare two JSON files, output the diff data to the terminal.
jsondiff run path/to/before.json path/to/after.json

# Output the diff data to a file.
jsondiff run path/to/before.json path/to/after.json -o path/to/result.diff

# Use a custom configuration file and output the diff data to a file.
jsondiff run path/to/before.json path/to/after.json -c path/to/config.json -o path/to/result.diff