JavaScript Text Differencing Library

Common errors

• TS2345: Argument of type '{ ignoreWhitespace: true; }' is not assignable to parameter of type 'DiffOptions'.

  cause Attempting to pass `ignoreWhitespace: true` as an option to `diffWords` when using TypeScript with `diff` v8+.
  fix The `ignoreWhitespace` option for `diffWords` is deprecated in TypeScript since v8. Instead, use `diffWordsWithSpace` for word diffs where whitespace significance matters, or simply `diffWords` if whitespace should be ignored by default.

• TypeError: Diff.parsePatch is not a function

  cause Incorrect CommonJS or ESM import syntax, or attempting to access methods on an undefined `Diff` object.
  fix For CommonJS, use `const { parsePatch } = require('diff');`. For ESM, use `import { parsePatch } from 'diff';` or `import * as Diff from 'diff';` and then `Diff.parsePatch(...)`. Ensure your module system is configured correctly for ESM if using Node.js.

• RangeError: Maximum call stack size exceeded (or similar memory exhaustion/infinite loop)

  cause Applying or parsing a maliciously crafted patch containing specific line break characters, triggering the CVE-2026-24001 vulnerability.
  fix Upgrade `diff` to version 8.0.3 or higher immediately. If unable to upgrade, sanitize patch input to remove `\r`, `\u2028`, or `\u2029` characters from filename and patch headers before processing.

• TypeError: Cannot read properties of undefined (reading 'diffChars')

  cause Occurs in browser environments when `diff.js` is loaded via a script tag but the global `Diff` object is not available or is incorrectly accessed.
  fix Ensure the `dist/diff.js` or `dist/diff.min.js` file is correctly loaded via a `<script>` tag. The library exposes its API via a global `Diff` object in this context. Example: `<script src="node_modules/diff/dist/diff.min.js"></script>` and then `Diff.diffChars(...)`.

Warnings

• breaking Version 8.0.0 introduced significant breaking changes. The source code was rewritten in TypeScript, and the library now ships its own type definitions. Users previously relying on `@types/diff` must remove this dependency when upgrading to v8 or newer. Many exported types for options arguments were also removed or refactored. `diffWords` behavior changed, and `ignoreWhitespace: true` for `diffWords` is deprecated in TypeScript in favor of `diffWordsWithSpace`.
  Fix: Remove `@types/diff` dependency. Review `diffWords` usage for `ignoreWhitespace` and consider `diffWordsWithSpace`. Update code to reflect changes in `diffJson`'s `stringifyReplacer` and async function return types. Consult release notes for a full list of changes.
• breaking Version 6.0.0 contained numerous breaking changes, including a radical alteration to `diffWords` behavior where runs of whitespace were previously treated as tokens, leading to unintuitive diffing. This was part of a larger effort to fix open bugs and design problems requiring breaking changes.
  Fix: Review `diffWords` usage, particularly with `ignoreWhitespace`. Test extensively after upgrading from versions prior to v6. Consult the v6.0.0 release notes for specific API changes.
• breaking Version 5.0.0 renamed the UMD export from `JsDiff` to `Diff`. Additionally, newlines were separated into distinct tokens for word diffs, and unified diffs were adjusted to match certain 'quirks' for broader compatibility.
  Fix: If using the UMD build, adjust global references from `JsDiff` to `Diff`. Be aware of changes in word diff tokenization and unified patch formatting.
• breaking The `parsePatch` and `applyPatch` methods in versions prior to 8.0.3, 5.2.2, 4.0.4, and 3.5.1 are vulnerable to Denial of Service (DoS) via infinite loops and inefficient regular expression complexity (ReDOS). Maliciously crafted patches containing specific line break characters (`\r`, `\u2028`, `\u2029`) in filename or patch headers can cause uncontrolled memory consumption or high CPU usage, leading to application crashes.
  Fix: Immediately upgrade to version 8.0.3 or later. If unable to upgrade, implement input validation to prevent parsing patches that contain `\r`, `\u2028`, or `\u2029` in any user-controlled patch content, especially headers.
• gotcha Importing specific internal modules directly, e.g., `require("diff/lib/diff/word.js")`, was broken in Node.js 17.5.0 and later due to changes in Node.js's interpretation of the `exports` field in `package.json`.
  Fix: Avoid direct imports from the `lib` folder. Always import directly from the top-level `diff` package (`import { diffWords } from 'diff';`) to ensure compatibility and correct module resolution. This was largely addressed with the v8 refactor.

Install

• npm install diff npm
• yarn add diff yarn
• pnpm add diff pnpm

Imports

• diffLines
  wrong:

  const diffLines = require('diff').diffLines;

  correct:

  import { diffLines } from 'diff';

  ESM imports are preferred since v8. Named exports for all diffing functions.
• createPatch
  wrong:

  const createPatch = require('diff').createPatch;

  correct:

  import { createPatch } from 'diff';

  ESM is the standard. CommonJS `require` can also be used but is less idiomatic for modern projects.
• Diff
  wrong:

  import Diff from 'diff';

  correct:

  import * as Diff from 'diff';

  The library exports many named functions, not a default export. Use `import * as Diff from 'diff'` or destructure specific functions.

Quickstart

Demonstrates a basic line-by-line text comparison and logs the changes with indicators.

import { diffLines } from 'diff';

const oldText = `Line One
Line Two
Line Three
Line Four`;
const newText = `Line A
Line Two Changed
Line Three
Line B`;

const changes = diffLines(oldText, newText);

console.log('--- Diff Results ---');
changes.forEach((part) => {
  const color = part.added ? 'green' : part.removed ? 'red' : 'grey';
  // For a real-world scenario, use a color library or styling for output
  const prefix = part.added ? '+ ' : part.removed ? '- ' : '  ';
  console.log(`${prefix}${part.value.replace(/\n/g, '\n' + prefix)}`, `(${color})`);
});

/* Example Output:
--- Diff Results ---
+ Line A (green)
- Line One (red)
  Line Two (grey)
+  Changed (green)
- Line Two (red)
  Line Three (grey)
+ Line B (green)
- Line Four (red)
*/