Merge Deep

3.0.3 · active · verified Sun Apr 19

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.

Common errors

```
ReferenceError: require is not defined
```
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`).

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.
```
TypeError: merge-deep is not a function
```
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(...)`).

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.
```
RangeError: Maximum call stack size exceeded
```
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.

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.

Warnings

gotcha 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.
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.
gotcha 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.
Fix: Manually merge arrays before passing them to `merge-deep` or use a different library if array concatenation is a primary requirement.
gotcha 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`.
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.
breaking 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`.
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.

Install

npm install merge-deep npm
yarn add merge-deep yarn
pnpm add merge-deep pnpm

Imports

merge
wrong:
```
import { merge } from 'merge-deep';
```
correct:
```
const merge = require('merge-deep');
```
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.
merge (ESM)
wrong:
```
const merge = require('merge-deep');
```
correct:
```
import merge from 'merge-deep';
```
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.

Quickstart

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.

const merge = require('merge-deep');

const obj1 = {
  a: {
    b: {
      c: 'c1',
      d: 'd1'
    },
    x: 1
  }
};

const obj2 = {
  a: {
    b: {
      e: 'e2',
      f: 'f2'
    },
    y: 2
  },
  z: 3
};

// Basic deep merge of two objects
const merged = merge(obj1, obj2);
console.log('Merged two objects:', merged);
// Expected: { a: { b: { c: 'c1', d: 'd1', e: 'e2', f: 'f2' }, x: 1, y: 2 }, z: 3 }

// Demonstrate merging multiple objects into a new empty object
const obj3 = { a: { b: { g: 'g3' } } };
const mergedMany = merge({}, obj1, obj2, obj3);
console.log('Merged multiple objects:', mergedMany);
// Expected to deeply merge properties from obj1, obj2, obj3 into a new empty object.

view raw JSON →