merge-json-webpack-plugin

6.2.1 verified Sat Apr 25 auth: no javascript

Webpack 5 plugin that merges multiple JSON files into a single output file during the build process. Version 6.2.1 is current, with a stable release cadence. Supports glob patterns for file selection, custom merge functions, optional output minification, and transformation hooks. Differentiates from simple file concatenation by performing deep merge with customizable merge strategy, and integrates directly as a webpack plugin. Requires webpack ^5.0.0 and Node >=12.20.0. Ships TypeScript definitions.

Common errors

error Error: Cannot find module 'merge-json-webpack-plugin' ↓

cause Missing installation or incorrect import path.

fix

Run npm install -D merge-json-webpack-plugin.

error TypeError: MergeJsonPlugin is not a constructor ↓

cause Importing the module incorrectly (e.g., default import vs named import).

fix

Use const MergeJsonPlugin = require('merge-json-webpack-plugin');.

error ValidationError: Invalid configuration object. Webpack has been initialized using a configuration object that does not match the API schema. ↓

cause Webpack version mismatch; plugin requires webpack 5.

fix

Update webpack to version 5: npm install -D webpack@5.

error Error: ENOENT: no such file or directory, open 'path/to/file.json' ↓

cause One of the source files specified in 'files' does not exist.

fix

Check that all file paths are correct and relative to webpack context or the plugin's cwd.

Warnings

breaking v5.0.0 dropped support for webpack 4 and Node <12. ↓

fix Upgrade to webpack 5 and Node >=12.

breaking v4.0.0 renamed from 'merge-json-webpack-plugin' (npm scoping change) but package name remained same; the plugin constructor changed from 'MergeJsonWebpackPlugin' to 'MergeJsonPlugin'. ↓

fix Use 'MergeJsonPlugin' instead of 'MergeJsonWebpackPlugin'.

deprecated The 'cwd' option may be deprecated in future; use webpack context instead. ↓

fix Use webpack's context option instead of passing cwd to the plugin.

gotcha When using 'pattern' option, the order of merged JSONs is not guaranteed; subsequent files may overwrite earlier ones arbitrarily. ↓

fix Use 'files' array instead, or ensure your transform/merge function handles order.

gotcha The 'transform' function must return a JSON-serializable object; returning a non-serializable value (e.g., undefined) will cause the output to be empty or malformed. ↓

fix Ensure transform always returns an object or null; if returning a promise, it must resolve to a valid object.

gotcha Using 'mergeFn' incorrectly can cause performance issues or infinite loops; custom merge functions are called recursively. ↓

fix Avoid mutating objects inside mergeFn; always return a new object.

Install

npm install merge-json-webpack-plugin

yarn add merge-json-webpack-plugin

pnpm add merge-json-webpack-plugin

Imports

MergeJsonPlugin
wrong
```
import MergeJsonPlugin from 'merge-json-webpack-plugin';
```
correct
```
const MergeJsonPlugin = require('merge-json-webpack-plugin');
```
The package does not export ESM; use CommonJS require in webpack config. Alternatively, if using ES modules for webpack config, use dynamic import: const MergeJsonPlugin = (await import('merge-json-webpack-plugin')).default;
type MergeJsonPluginOptions
```
import type { MergeJsonPluginOptions } from 'merge-json-webpack-plugin';
```
TypeScript users can import the options type directly; the package provides bundled types.
MergeJsonPlugin (default import with type assertion)
wrong
```
import MergeJsonPlugin = require('merge-json-webpack-plugin');
```
correct
```
const MergeJsonPlugin = require('merge-json-webpack-plugin');
```
In TypeScript, avoid the import = require syntax; use ordinary require with @types/node or a simple const declaration.

Quickstart

Basic webpack config that merges common.json and overrides.json into manifest.json, with optional version injection and minification.

// webpack.config.js
const MergeJsonPlugin = require('merge-json-webpack-plugin');
const path = require('path');

module.exports = {
  plugins: [
    new MergeJsonPlugin({
      groups: [
        {
          files: ['common.json', 'overrides.json'],
          to: 'manifest.json',
          transform: (merged) => {
            merged.version = process.env.APP_VERSION || '1.0.0';
            return merged;
          },
        },
      ],
      minify: process.env.NODE_ENV === 'production',
    }),
  ],
};