{"id":15259,"library":"variable-diff","title":"Visual Variable Diff","description":"variable-diff is a JavaScript/TypeScript library designed to generate a visual diff between two JavaScript variables, primarily objects or JSON structures. It focuses on presenting only the differences (additions, deletions, and modifications) in a human-readable, formatted output, making it easier to identify changes without sifting through identical data. The current stable version is 2.0.2. While there isn't an explicit release cadence, the project appears to be actively maintained, with recent updates introducing new features like an options argument in version 2.0.1. Its key differentiator is its emphasis on clear, colored, and indented output directly within the console or logs, making it particularly useful for debugging and comparing configuration objects or data states efficiently.","status":"active","version":"2.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/taylorhakes/variable-diff","tags":["javascript","diff","visual","json","object","variable","difference","changes","typescript"],"install":[{"cmd":"npm install variable-diff","lang":"bash","label":"npm"},{"cmd":"yarn add variable-diff","lang":"bash","label":"yarn"},{"cmd":"pnpm add variable-diff","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary `diff` function is exported as a default export in ES Module (ESM) contexts. Using a named import will result in `undefined` for `diff`.","wrong":"import { diff } from 'variable-diff';","symbol":"diff","correct":"import diff from 'variable-diff';"},{"note":"This is the standard CommonJS import pattern, as shown in the library's README examples for Node.js environments.","symbol":"diff (CommonJS)","correct":"const diff = require('variable-diff');"},{"note":"For TypeScript users, the `DiffOptions` interface can be imported to type the options object passed to the `diff` function, providing type safety for configuration.","symbol":"DiffOptions (Type)","correct":"import type { DiffOptions } from 'variable-diff';"}],"quickstart":{"code":"import diff from 'variable-diff';\n\ninterface UserProfile {\n  id: string;\n  name: string;\n  email: string;\n  preferences?: {\n    theme: 'dark' | 'light';\n    notifications: boolean;\n    language: string;\n  };\n  roles: string[];\n}\n\nconst oldProfile: UserProfile = {\n  id: 'user_123',\n  name: 'Alice Smith',\n  email: 'alice@example.com',\n  preferences: {\n    theme: 'dark',\n    notifications: true,\n    language: 'en-US'\n  },\n  roles: ['user', 'editor']\n};\n\nconst newProfile: UserProfile = {\n  id: 'user_123',\n  name: 'Alice Johnson',\n  email: 'alice.johnson@example.com',\n  preferences: {\n    theme: 'light',\n    notifications: false,\n    language: 'en-GB'\n  },\n  roles: ['user', 'admin']\n};\n\nconst diffOptions = {\n  indent: '  ', // 2 spaces for indentation\n  newLine: '\\n', // Newline character\n  color: true // Enable colored output, set to false for plain text\n};\n\nconsole.log('--- Profile Changes ---\\n');\nconst result = diff(oldProfile, newProfile, diffOptions);\nconsole.log(result.text);\n\nif (result.changed) {\n  console.log('\\nDetected changes in profile data.');\n} else {\n  console.log('\\nNo changes detected in profile data.');\n}\n\n// Accessing programmatic changes (raw object)\n// console.log('\\nRaw changes object:', JSON.stringify(result.changes, null, 2));","lang":"typescript","description":"Demonstrates the basic usage of `variable-diff` to visually compare two TypeScript objects (simulated user profiles), highlighting changes with custom indentation and color options, and also showing how to check if changes were detected programmatically."},"warnings":[{"fix":"To ensure universal readability, set `color: false` in the options object if the output target does not support ANSI colors. If using a custom `wrap` function, ensure the coloring library is installed and compatible with the target environment, or provide a fallback without colors.","message":"When `color: true` (the default) or a custom `wrap` function (e.g., using `chalk`) is utilized, the output relies on ANSI escape codes for coloring. These codes may not render correctly in all environments, potentially showing raw escape sequences instead of colors (e.g., some non-TTY output streams or basic text editors).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use `import diff from 'variable-diff';` for ES Modules. For CommonJS, use `const diff = require('variable-diff');`.","message":"For ES Module environments, `variable-diff` uses a default export for its primary `diff` function. Incorrectly attempting a named import (`import { diff } from 'variable-diff';`) will lead to `diff` being `undefined`.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Before diffing, preprocess objects to break circular references, for example, by serializing and deserializing (`JSON.parse(JSON.stringify(obj))`) if possible, or by explicitly removing properties that cause circularity.","message":"Comparing objects with circular references (where an object directly or indirectly references itself) might lead to infinite loops or unexpected behavior, as the library's diffing algorithm may not inherently detect and handle all such cases gracefully.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Correct the import statement: for CommonJS, use `const diff = require('variable-diff');`; for ES Modules, use `import diff from 'variable-diff';`.","cause":"This error commonly occurs when `variable-diff` is imported incorrectly. In CommonJS, trying `require('variable-diff').diff` or in ESM, using `import { diff } from 'variable-diff';` will cause this because `diff` is a default export.","error":"TypeError: diff is not a function"},{"fix":"To resolve, either install `chalk` as a dependency (`npm install chalk`) if you intend to use its coloring features, or remove the `wrap` function from your options to let `variable-diff` use its default color handling (or no colors if `color: false` is set).","cause":"If you copy the `wrap` function example from the library's `defaultOptions` snippet (which implicitly uses the `chalk` library for coloring) into your options without having `chalk` installed in your project, this error will occur.","error":"ReferenceError: chalk is not defined"}],"ecosystem":"npm"}