Patchers Overview

The @xtarterize/patchers package provides utilities for safely modifying configuration files without overwriting existing customizations.

Available Patchers

Patcher	Description
`mergeJson`	Deep merge JSON objects using `defu` — existing keys take precedence
`mergeYaml`	Deep merge YAML objects using `defu` and `js-yaml`
`injectVitePlugin`	AST-based plugin injection into `vite.config.ts` using `magicast`

Architecture

flowchart TD
    Task[Conformance Task] --> P{Which patcher?}
    P -->|JSON config| MJ[mergeJson<br/>defu deep merge]
    P -->|YAML config| MY[mergeYaml<br/>defu + js-yaml]
    P -->|Vite config| AP[injectVitePlugin<br/>magicast AST]
    
    MJ --> W[Write file]
    MY --> W
    AP --> W
    
    style Task fill:#6366f1,color:#fff
    style MJ fill:#22c55e,color:#fff
    style MY fill:#22c55e,color:#fff
    style AP fill:#22c55e,color:#fff

JSON Merge

import { mergeJson } from '@xtarterize/patchers'

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

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

YAML Merge

import { mergeYaml } from '@xtarterize/patchers'

const existing = `
name: CI
on:
  push:
    branches: [main]
`

const incoming = `
name: CI
on:
  pull_request:
    branches: [main]
`

const merged = mergeYaml(existing, incoming)
// Both push and pull_request triggers preserved

AST Patching (Vite Plugins)

import { injectVitePlugin } from '@xtarterize/patchers'

const result = await injectVitePlugin(
  '/path/to/vite.config.ts',
  'vite-plugin-checker',    // import path
  'checker',                // import name
  'checker({ typescript: true })'  // plugin expression
)

if (!result.success) {
  console.log(result.fallback) // Manual instructions if AST structure is unsupported
}

Parse — Parses vite.config.ts using magicast
Check — Checks if the plugin is already imported (idempotent)
Insert import — Inserts the import at the top of the file
Append plugin — Appends the plugin call to the plugins array
Write — Writes the file back