{"id":12720,"library":"diff","title":"JavaScript Text Differencing Library","description":"The `diff` (also known as `jsdiff`) library provides a robust JavaScript implementation for calculating differences between texts. Based on the efficient Myers O(ND) algorithm, it offers various comparison granularities, including character, word, line, CSS token, and JSON object differencing. The library is currently at stable version 9.0.0, released recently (April 2026), and maintains an active development cycle with frequent updates addressing performance, features, and critical bug fixes. Major versions, particularly v6 and v8, have introduced significant breaking changes and refactors, including a transition to bundled TypeScript types in v8. `jsdiff` stands out for its comprehensive API, enabling not only difference calculation but also the creation and application of unified diff patches. It supports modern Node.js environments and widely available browser runtimes, and is a zero-dependency package, making it a lightweight yet powerful utility for tasks like code reviews, version control, and data synchronization.","status":"active","version":"9.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/kpdecker/jsdiff","tags":["javascript","diff","jsdiff","compare","patch","text","json","css","typescript"],"install":[{"cmd":"npm install diff","lang":"bash","label":"npm"},{"cmd":"yarn add diff","lang":"bash","label":"yarn"},{"cmd":"pnpm add diff","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM imports are preferred since v8. Named exports for all diffing functions.","wrong":"const diffLines = require('diff').diffLines;","symbol":"diffLines","correct":"import { diffLines } from 'diff';"},{"note":"ESM is the standard. CommonJS `require` can also be used but is less idiomatic for modern projects.","wrong":"const createPatch = require('diff').createPatch;","symbol":"createPatch","correct":"import { createPatch } from 'diff';"},{"note":"The library exports many named functions, not a default export. Use `import * as Diff from 'diff'` or destructure specific functions.","wrong":"import Diff from 'diff';","symbol":"Diff","correct":"import * as Diff from 'diff';"}],"quickstart":{"code":"import { diffLines } from 'diff';\n\nconst oldText = `Line One\nLine Two\nLine Three\nLine Four`;\nconst newText = `Line A\nLine Two Changed\nLine Three\nLine B`;\n\nconst changes = diffLines(oldText, newText);\n\nconsole.log('--- Diff Results ---');\nchanges.forEach((part) => {\n  const color = part.added ? 'green' : part.removed ? 'red' : 'grey';\n  // For a real-world scenario, use a color library or styling for output\n  const prefix = part.added ? '+ ' : part.removed ? '- ' : '  ';\n  console.log(`${prefix}${part.value.replace(/\\n/g, '\\n' + prefix)}`, `(${color})`);\n});\n\n/* Example Output:\n--- Diff Results ---\n+ Line A (green)\n- Line One (red)\n  Line Two (grey)\n+  Changed (green)\n- Line Two (red)\n  Line Three (grey)\n+ Line B (green)\n- Line Four (red)\n*/","lang":"typescript","description":"Demonstrates a basic line-by-line text comparison and logs the changes with indicators."},"warnings":[{"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.","message":"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`.","severity":"breaking","affected_versions":">=8.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=6.0.0 <7.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0 <6.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<8.0.3, <5.2.2, <4.0.4, <3.5.1"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0 <8.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to pass `ignoreWhitespace: true` as an option to `diffWords` when using TypeScript with `diff` v8+.","error":"TS2345: Argument of type '{ ignoreWhitespace: true; }' is not assignable to parameter of type 'DiffOptions'."},{"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.","cause":"Incorrect CommonJS or ESM import syntax, or attempting to access methods on an undefined `Diff` object.","error":"TypeError: Diff.parsePatch is not a function"},{"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.","cause":"Applying or parsing a maliciously crafted patch containing specific line break characters, triggering the CVE-2026-24001 vulnerability.","error":"RangeError: Maximum call stack size exceeded (or similar memory exhaustion/infinite loop)"},{"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(...)`.","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.","error":"TypeError: Cannot read properties of undefined (reading 'diffChars')"}],"ecosystem":"npm"}