deepmerge

deepmerge is a small JavaScript utility that recursively merges the enumerable properties of two or more objects, returning a new merged object without mutating either input. Where a key exists in both objects, the value from the later object wins; nested objects are merged recursively rather than overwritten, and arrays are concatenated by default (with a fully customizable merge strategy).

The library exposes both a merge(x, y, options) function for two objects and a merge.all(arrayOfObjects, options) helper for combining any number of objects at once. Its behavior is highly configurable via an arrayMerge function (to overwrite, concatenate, or index-combine arrays), an isMergeableObject predicate (to control which values get deep-merged vs. copied as-is), and a customMerge function (to override merge behavior per property key) — all while remaining a tiny, dependency-free UMD bundle usable in Node.js or directly in the browser.

What You Get

• A merge(x, y, [options]) function that deeply combines two objects into a new, non-mutated result
• A merge.all(arrayOfObjects, [options]) helper for merging any number of objects in one call
• Configurable array-merge strategy (arrayMerge option) — concatenate, overwrite, or index-combine arrays, or supply a fully custom function
• An isMergeableObject option to control which values are deep-merged versus copied wholesale (useful for class instances or special objects)
• A customMerge option to override merge behavior for specific property keys
• A tiny UMD bundle (~723 bytes minified+gzipped) usable via CommonJS, or directly in the browser without a bundler

Common Use Cases

• Merging default configuration objects with user-supplied overrides while preserving nested defaults
• Combining multiple partial state or options objects into a single object in application or library code
• Merging JSON configuration files (e.g. environment-specific config layered over base config)
• Building plugin or middleware systems where each layer contributes partial configuration that must be deeply combined

Under The Hood

Architecture - deepmerge is implemented as a single, compact index.js (~106 lines) exporting a recursive merge function plus a merge.all wrapper; the core algorithm walks the target and source objects’ keys, recursively merging nested mergeable objects and delegating array handling to a pluggable arrayMerge strategy function, with cloneUnlessOtherwiseSpecified ensuring untouched values are still cloned to avoid mutating inputs. Tech Stack - Plain JavaScript (with a small TypeScript declaration file, index.d.ts) built and bundled via Rollup into a UMD module, with zero runtime dependencies, making it safe to use in both Node.js and browser contexts without a build step. Code Quality - The test/ directory covers custom array-merge strategies, custom isMergeableObject predicates, merge.all, and — notably — a dedicated prototype-poisoning.js test guarding against __proto__-based prototype pollution attacks, a security-conscious addition given how widely the library is used to merge untrusted input; despite no commits since 2023, the codebase is stable and the API has not needed to change. API Design - The API is minimal and predictable (merge, merge.all, plus three well-documented options), with clear semantics (later value wins, arrays concatenate by default, nested objects merge recursively) that make it a near drop-in replacement wherever Object.assign-style shallow merging falls short.