Merge JSON CLI Tool

1.0.4 verified Thu Apr 23 auth: no javascript

The `merge-json-cli` package (current stable version 1.0.4) is a lean command-line utility designed for merging multiple JSON files into a single output. It introduces a custom "spread syntax" (`"..."`) directly within JSON objects and arrays, allowing developers to declaratively reference external JSON files or specific paths within them using JSON pointers. This enables dynamic composition of complex configurations from modular JSON fragments. The tool supports both object and array merging, including the use of glob patterns for array-based merges. As a CLI tool, its release cadence is driven by feature enhancements and bug fixes rather than a fixed schedule. Its primary differentiator is the in-JSON spread syntax, providing an intuitive way to manage hierarchical data structures across multiple files. It requires Node.js version 18.3.0 or higher.

Common errors

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

cause A JSON file specified in a `"..."` spread operator within your input JSON does not exist at the provided path, or the path is incorrect.

fix

Correct the file path specified in the "..." value within your JSON configuration, or ensure the referenced file is present at that location.

error SyntaxError: Unexpected token '...' ↓

cause The input JSON file contains invalid JSON syntax that prevents standard JSON parsing before `merge-json-cli` can process its custom spread operators.

fix

Validate all your input JSON files for correct JSON syntax using a linter or an online JSON validator to fix any parsing errors.

error Error: The 'merge-json-cli' package requires Node.js version >=18.3.0. You are running vX.Y.Z. ↓

cause The Node.js version installed on your system is older than the minimum required by `merge-json-cli`.

fix

Update your Node.js installation to version 18.3.0 or newer using a Node.js version manager like nvm or by downloading the latest LTS release from the official Node.js website.

Warnings

gotcha The `merge-json-cli` package requires Node.js version 18.3.0 or higher. Running it with an older version will result in an error. ↓

fix Ensure your Node.js environment is updated to version 18.3.0 or newer before running the CLI tool.

gotcha Paths specified in the JSON spread syntax (`"..."`) must be valid file paths or JSON pointers. Incorrectly formatted paths will lead to file not found errors or parsing issues. ↓

fix Verify that all paths used with `"..."` correctly point to existing JSON files or valid nested keys within those files (e.g., `./my-data.json` or `./config.json#/app/settings`).

gotcha Referenced JSON files must exist and be accessible relative to the primary input file or current working directory. If a file cannot be found, the merge operation will fail. ↓

fix Double-check the existence and permissions of all JSON files referenced within your configurations. Use absolute paths if relative paths cause ambiguity.

gotcha Command line arguments require correct syntax for input (`--in|-i`) and output (`--out|-o`). Misspellings or incorrect formatting will prevent the tool from executing. ↓

fix Always use `--in <file>` or `-i <file>` for the source JSON, and `--out <file>` or `-o <file>` for the target output file.

Install

npm install merge-json-cli

yarn add merge-json-cli

pnpm add merge-json-cli

Quickstart

Demonstrates how to run the `merge-json-cli` tool directly using `npx` to merge an input JSON file that references another JSON file via its custom spread syntax, outputting the consolidated result.

npx merge-json-cli --in ./input.json --out ./output.json

# Example input.json:
# {
#     "configName": "MyApp",
#     "version": "1.0.0",
#     "...": "./features.json",
#     "settings": {
#         "theme": "dark"
#     }
# }

# Example features.json (referenced by input.json):
# {
#     "featureA": true,
#     "featureB": false
# }

# The command will merge input.json, incorporating features.json,
# and write the result to output.json.