merge-deep

library3.0.3jsnpmunverified

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.

serialization

npm install merge-deep

github ↗package ↗

INSTALL

IMPORT

SIG · MERGE-DEEP

merge-deep

serializationjavascriptv3.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

merge

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

✗ import { merge } from '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)

✓ import merge from 'merge-deep';

✗ const merge = require('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.

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.

Debug

Known issues

gotchaWhen 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.

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

gotchaThis 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.

affects: >=1.0.0

breakingAs `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.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined

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

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

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.

Upgrade

Version history

3.0.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/jonschlinkert/merge-deep ↗

packagehttps://www.npmjs.com/package/merge-deep ↗