gulp-merge-json

A gulp plugin for deep-merging multiple JSON files into one file. Export as JSON or a node module.

Usage

1gulp.src('jsonFiles/**/*.json')
2	.pipe(merge(options))
3	.pipe(gulp.dest('./dist'));

Options

Key	Type	Default	Description
fileName	String	combined.json	Output filename
edit	Function	json => json	Edit function (add/remove/edit keys during merge)
transform	Function	json => json	Transform final merged object (similar to edit but applied at the end)
startObj	Object/Array	{}	Starting object to merge into (useful for providing default values)
endObj	Object/Array		Object to merge after file merging complete (useful for overwriting with special values)
exportModule	Boolean/String	false	Output module.exports = {MERGED_JSON_DATA}; or {exportModule} = {MERGED_JSON_DATA} when string passed
concatArrays	Boolean	false	Whether to concatenate arrays instead of merging
mergeArrays	Boolean	true	Whether to merge arrays or overwrite completely
customizer	Function		Custom merge function for use with mergeWith
jsonReplacer	Function		Custom JSON replacer function passed to stringify
jsonSpace	String	\t	String used for white space by stringify
json5	Boolean	false	Use JSON5 instead of JSON for parse and stringify

Examples

1var merge = require('gulp-merge-json');
2
3/**
4 * Basic functionality
5 */
6gulp.src('jsonFiles/**/*.json')
7	.pipe(merge())
8	.pipe(gulp.dest('./dist'));
9
10/**
11 * Edit JSON with function
12 */
13gulp.src('jsonFiles/**/*.json')
14	.pipe(merge({
15		fileName: 'file.json',
16		edit: (parsedJson, file) => {
17			if (parsedJson.someValue) {
18				delete parsedJson.otherValue;
19			}
20
21			return parsedJson;
22		},
23	}))
24	.pipe(gulp.dest('./dist'));
25
26/**
27 * Edit final JSON with transformer function
28 */
29gulp.src('jsonFiles/**/*.json')
30	.pipe(merge({
31		fileName: 'file.json',
32		transform: (mergedJson) => {
33			return {
34				key: {
35					type: 'data',
36					...mergedJson,
37				};
38			};
39		},
40	}))
41	.pipe(gulp.dest('./dist'));
42
43/**
44 * Provide a default object (files are merged in order so object values will be overwritten)
45 */
46gulp.src('jsonFiles/**/*.json')
47	.pipe(merge({
48		startObj: { someKey: 'defaultValue' },
49	}))
50	.pipe(gulp.dest('./dist'));
51
52/**
53 * Provide an overwriting object (merged at the end)
54 */
55gulp.src('jsonFiles/**/*.json')
56	.pipe(merge({
57		endObj: { someKey: 'specialValue' },
58	}))
59	.pipe(gulp.dest('./dist'));
60
61/**
62 * Output module.exports = {JSON_DATA}
63 */
64gulp.src('jsonFiles/**/*.json')
65	.pipe(merge({
66		exportModule: true,
67	}))
68	.pipe(gulp.dest('./dist'));
69
70/**
71 * Output a custom variable = {JSON_DATA}
72 */
73gulp.src('jsonFiles/**/*.json')
74	.pipe(merge({
75		fileName: 'dataModule.js',
76		exportModule: 'const myVar',
77	}))
78	.pipe(gulp.dest('./dist'));
79
80/**
81 * Provide replacer and space options for JSON.stringify
82 */
83gulp.src('jsonFiles/**/*.json')
84    .pipe(merge({
85        jsonSpace: '  ',
86        jsonReplacer: (key, value) => {/*...*/}
87    })
88    .pipe(gulp.dest('./dist'));
89
90/**
91 * Use a customizer function for custom merging behavior
92 */
93gulp.src('jsonFiles/**/*.json')
94  .pipe(merge({
95    customizer: (objA, objB) => {
96      // Example: Concat arrays but only keep unique values
97      if (Array.isArray(objA) && Array.isArray(objB)) {
98        return objA.concat(objB).filter((item, index, array) => (
99          array.indexOf(item) === index
100        ));
101      }
102
103      return undefined;
104    },
105  }))
106  .pipe(gulp.dest('./dist'));
107
108/**
109 * JSON5
110 */
111gulp.src('jsonFiles/**/*.json5')
112	.pipe(merge({
113		json5: true,
114	}))
115	.pipe(gulp.dest('./dist'));

Example Input

1/*
2	json/defaults.json
3 */
4{
5	"key1": {
6		"data1": "value1",
7		"data2": "value2"
8	},
9	"key2": {
10		"dataA": "valueA",
11		"dataB": {
12			"a": "b",
13			"c": "d"
14		}
15	}
16}
17
18/*
19	json/development.json
20 */
21{
22	"key1": {
23		"data1": "devValue"
24	},
25	"key2": {
26		"dataB": {
27			"c": "DEV MODE!"
28		}
29	},
30	"key3": {
31		"important": "value"
32	}
33}

Example Output

1/*
2	dist/combined.json
3 */
4{
5	"key1": {
6		"data1": "devValue",
7		"data2": "value2"
8	},
9	"key2": {
10		"dataA": "valueA",
11		"dataB": {
12			"dataA": "valueA",
13			"dataB": {
14				"a": "b",
15				"c": "DEV MODE!"
16			}
17		}
18	},
19	"key3": {
20		"important": "value"
21	}
22}