JSON/JSONC/JSON5 deep-merger CLI for Node 22+
npm install @gradientedge/merge-jsonc> Secure, fast JSON / JSONC / JSON5 deep-merging utility and CLI for Node 22+
> Built for composable configuration files such as Wrangler, Vite, or Next.js.
---
merge-jsonc lets you combine multiple .json, .jsonc, or .json5 files in order, producing a single merged output where later files override earlier ones.
It's designed for config layering (base โ local โ environment), with:
- โก Deep merge support (deepmerge under the hood)
- ๐ง Incremental builds โ skips work when inputs or content haven't changed
- ๐ Path-safe โ resists directory-traversal and symlink escapes (Snyk-friendly)
- ๐งพ Multi-format aware โ parses JSON, JSONC (comments), and JSON5 (extended syntax)
- ๐ Auto-creates directories โ output paths with missing parent directories are created automatically
- ๐ชถ ESM-only, Node 22+ โ zero legacy baggage
---
``bash`
npm install @gradientedge/merge-jsonc
---
`bashMerge multiple config files
merge-jsonc --out final.json base.json dev.jsonc local.json5
---
๐ Usage
$3
`bash
merge-jsonc [options] Options:
-o, --out Output file path [default: "combined.jsonc"]
--skip-missing Ignore missing input files [boolean] [default: false]
--min Minified output [boolean] [default: false]
--dry-run Preview without writing files [boolean] [default: false]
--backup Create .bak before overwriting [boolean] [default: false]
-q, --quiet Suppress non-error output [boolean] [default: false]
--indent Custom indentation spaces [number]
--array-merge Array merge strategy [choices: "replace", "concat"] [default: "replace"]
-h, --help Show help
-v, --version Show version
`$3
`typescript
import { mergeJsonc } from "@gradientedge/merge-jsonc";const result = mergeJsonc({
inputs: ["base.json", "dev.jsonc", "local.json5"],
out: "config.json",
skipMissing: true,
arrayMerge: "replace", // or "concat"
});
console.log(result.wrote ? "Merged!" : result.reason);
`---
๐ Array Merge Strategies
By default,
merge-jsonc replaces arrays when merging. You can configure this behavior:$3
Arrays from later files completely replace arrays from earlier files:
`json
// base.json
{ "items": [1, 2, 3] }// override.json
{ "items": [4, 5] }
// Result with --array-merge replace (default)
{ "items": [4, 5] }
``bash
merge-jsonc base.json override.json --out result.json
or explicitly:
merge-jsonc base.json override.json --out result.json --array-merge replace
`$3
Arrays are concatenated together:
`json
// base.json
{ "items": [1, 2, 3] }// override.json
{ "items": [4, 5] }
// Result with --array-merge concat
{ "items": [1, 2, 3, 4, 5] }
``bash
merge-jsonc base.json override.json --out result.json --array-merge concat
`$3
You can also set the array merge strategy in your config file:
`javascript
// .merge-jsonc.config.mjs
export default {
arrayMerge: "concat",
backup: true,
pretty: true,
};
`---
๐คซ Quiet Mode for Scripting
Use
--quiet (or -q) to suppress all non-error output, perfect for CI/CD pipelines and automated workflows:`bash
Silent operation - only errors are shown
merge-jsonc -q --out config.json base.json override.jsonUse in scripts with exit code checking
if merge-jsonc -q --out config.json *.jsonc; then
echo "Config merged successfully"
fi
`Errors are still displayed even with
--quiet, ensuring debugging information is available when needed.---
๐งช Examples
examples/ directory for real-world usage patterns:- Vite Config: Layer base, dev, and local Vite configurations
- Wrangler Config: Merge Cloudflare Workers configurations
- JSON5 Features: Demonstrate JSON5 syntax with comments and trailing commas
---
๐ก๏ธ Security Features
- Path Traversal Protection: Prevents
../ attacks and symlink escapes
- File Type Validation: Only processes .json, .jsonc, and .json5 files
- Atomic Writes: Uses temporary files to prevent corruption
- Snyk Compliant: Passes security audits for enterprise use---
๐ง Development
`bash
Install dependencies
npm installFormat code (ensures JSONC files have no trailing commas)
npm run formatCheck formatting
npm run format:checkRun linting
npm run lintRun tests (66 comprehensive tests)
npm testBuild the project
npm run buildTest locally
npm run prepublishOnly
``---
MIT ยฉ Gradient Edge