JSON Merge

JSON Merge

The mergeJson function performs a deep merge of two JavaScript objects using the defu library. It’s used whenever Xtarterize needs to modify JSON configuration files like tsconfig.json, biome.json, or .vscode/settings.json.

Usage

import { mergeJson } from '@xtarterize/patchers'

const existing = { compilerOptions: { strict: true, target: "ES2022" } }
const incoming = { compilerOptions: { incremental: true } }

const merged = mergeJson(existing, incoming)
// { compilerOptions: { strict: true, target: "ES2022", incremental: true } }

Parameters

Parameter	Type	Description
existing	object	The current configuration (takes precedence)
incoming	object	The new configuration to merge in (fills gaps)

Return Value

Returns the merged object. Existing keys always take precedence over incoming keys.

Deep Merge Behavior

Nested objects are merged recursively:

const existing = {
  compilerOptions: {
    strict: true,
    target: "ES2022"
  }
}

const incoming = {
  compilerOptions: {
    incremental: true,
    tsBuildInfoFile: ".tsbuildinfo"
  }
}

const merged = mergeJson(existing, incoming)
// {
//   compilerOptions: {
//     strict: true,           // preserved from existing
//     target: "ES2022",       // preserved from existing
//     incremental: true,      // added from incoming
//     tsBuildInfoFile: ".tsbuildinfo"  // added from incoming
//   }
// }

Merge Flow

flowchart TD
    E[Existing config] --> M{mergeJson}
    I[Incoming config] --> M
    M --> P{Key exists?}
    P -->|Yes| K[Keep existing value]
    P -->|No| A[Add incoming value]
    P -->|Nested object| R[Recurse merge]
    K --> O[Merged result]
    A --> O
    R --> O
    
    style E fill:#6366f1,color:#fff
    style I fill:#f59e0b,color:#fff
    style O fill:#22c55e,color:#fff

Array Handling

Caution

Arrays are replaced, not merged. This is defu’s default behavior. For cases where arrays need to be combined (like Vite plugins), use the AST patcher instead.

const existing = { plugins: ['pluginA'] }
const incoming = { plugins: ['pluginB'] }

const merged = mergeJson(existing, incoming)
// { plugins: ['pluginA'] } — existing wins

Real-World Examples

tsconfig.json

// Existing
const existing = { compilerOptions: { strict: true, target: "ES2022" } }
// Incoming: add incremental builds
const incoming = { compilerOptions: { incremental: true } }
// Result: both preserved

biome.json

// Existing
const existing = { linter: { enabled: true } }
// Incoming: add formatter
const incoming = { formatter: { enabled: true } }
// Result: both sections present

.vscode/settings.json

// Existing
const existing = { "editor.formatOnSave": true }
// Incoming: add Biome formatter
const incoming = { "[typescript]": { "editor.defaultFormatter": "biomejs.biome" } }
// Result: both settings preserved