{"id":11298,"library":"merge-deep","title":"Merge Deep","description":"merge-deep is a JavaScript utility designed to recursively merge the properties of one or more source objects into a target object. It is currently at stable version 3.0.3, maintaining a mature and relatively stable codebase. The library's core functionality is to perform a deep merge, meaning it traverses nested objects and combines their properties rather than simply overwriting them, which is a common behavior in shallow merge operations. This ensures a comprehensive union of object structures. It draws its implementation foundation from the `mout` library's merge utility. While a specific release cadence isn't explicitly defined, the project typically receives updates for maintenance or minor enhancements. A key differentiator is its commitment to a pure function approach, aiming to return a new merged object without directly mutating the input objects, providing a predictable and side-effect-free way to combine complex configurations or data structures.","status":"active","version":"3.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/jonschlinkert/merge-deep","tags":["javascript","clone","clone-deep","copy","deep","deep-clone","deep-merge","extend","key"],"install":[{"cmd":"npm install merge-deep","lang":"bash","label":"npm"},{"cmd":"yarn add merge-deep","lang":"bash","label":"yarn"},{"cmd":"pnpm add merge-deep","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `merge-deep` package is a CommonJS module that exports its main function as a default. Attempting to use a named ESM import will result in `undefined` or a module resolution error.","wrong":"import { merge } from 'merge-deep';","symbol":"merge","correct":"const merge = require('merge-deep');"},{"note":"In an ES Module environment (`'type': 'module'` in package.json or `.mjs` files), Node.js and bundlers may allow default importing CommonJS modules. However, direct `require()` calls are not available in native ESM.","wrong":"const merge = require('merge-deep');","symbol":"merge (ESM)","correct":"import merge from 'merge-deep';"}],"quickstart":{"code":"const merge = require('merge-deep');\n\nconst obj1 = {\n  a: {\n    b: {\n      c: 'c1',\n      d: 'd1'\n    },\n    x: 1\n  }\n};\n\nconst obj2 = {\n  a: {\n    b: {\n      e: 'e2',\n      f: 'f2'\n    },\n    y: 2\n  },\n  z: 3\n};\n\n// Basic deep merge of two objects\nconst merged = merge(obj1, obj2);\nconsole.log('Merged two objects:', merged);\n// Expected: { a: { b: { c: 'c1', d: 'd1', e: 'e2', f: 'f2' }, x: 1, y: 2 }, z: 3 }\n\n// Demonstrate merging multiple objects into a new empty object\nconst obj3 = { a: { b: { g: 'g3' } } };\nconst mergedMany = merge({}, obj1, obj2, obj3);\nconsole.log('Merged multiple objects:', mergedMany);\n// Expected to deeply merge properties from obj1, obj2, obj3 into a new empty object.","lang":"javascript","description":"This quickstart demonstrates how to import and use `merge-deep` to perform a basic deep merge on two objects and then on multiple objects into a new target."},"warnings":[{"fix":"Pre-process objects to extract or specially handle non-plain object types, or use a custom cloning strategy before merging if preserving specific object types is critical.","message":"When merging objects containing non-plain objects such as `Date` objects, `RegExp` instances, or custom class instances, `merge-deep` will typically clone them as plain objects, losing their original type or prototype chain. This is a common behavior in many deep merge utilities but can lead to loss of functionality for complex objects.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Manually merge arrays before passing them to `merge-deep` or use a different library if array concatenation is a primary requirement.","message":"The library performs a deep merge, but arrays are typically overwritten rather than concatenated if a source object provides an array value for an existing array property on the target. This can lead to unexpected data loss if array concatenation is expected.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure objects are free of circular references or use a library specifically designed to handle them. Tools like `flatted` can help detect and serialize/deserialize such structures.","message":"This utility does not explicitly handle circular references within objects. Merging objects with circular structures may lead to an infinite loop and a `RangeError: Maximum call stack size exceeded`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For Node.js projects, use `const merge = require('merge-deep');`. For browser or ESM-only environments, ensure your bundler (e.g., Webpack, Rollup) is configured to handle CommonJS modules or consider an alternative library with native ESM support.","message":"As `merge-deep` is a CommonJS-first module, attempting to use ES Module `import` syntax directly in an ESM environment without proper transpilation or bundler configuration can lead to module resolution errors or `TypeError: merge-deep is not a function`.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Either revert your project or file to CommonJS (`.cjs` file extension or remove `'type': 'module'`) or use dynamic import `import('merge-deep').then(module => module.default || module);` if your environment supports it.","cause":"Attempting to use `require()` in an ES Module context (e.g., a file with `.mjs` extension or a project with `'type': 'module'` in `package.json`).","error":"ReferenceError: require is not defined"},{"fix":"Change the import statement to `import merge from 'merge-deep';` if your environment supports default ESM imports from CJS modules, or preferably `const merge = require('merge-deep');` in a CommonJS context.","cause":"This error often occurs when attempting to use a named ESM import (`import { merge } from 'merge-deep';`) when the module exports a default function via CommonJS (`module.exports = function merge(...)`).","error":"TypeError: merge-deep is not a function"},{"fix":"Inspect the objects for circular references and remove them, or preprocess the objects using a utility that can detect and handle or flatten circular structures before merging.","cause":"Merging objects that contain circular references (an object property directly or indirectly references itself), causing the recursive merge function to enter an infinite loop.","error":"RangeError: Maximum call stack size exceeded"}],"ecosystem":"npm"}