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 } }

Tip

The defu library ensures that existing user configuration is never overwritten - incoming values only fill gaps. Learn more in the JSON Merge reference.

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({
  configPath: '/path/to/vite.config.ts',
  importPath: 'vite-plugin-checker',
  importName: 'checker',
  pluginExpression: 'checker({ typescript: true })',
})

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

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

Note

If the config structure is non-standard (factory functions, conditional exports), the AST patcher falls back to returning manual instructions rather than corrupting the file.

References

• defu - Deep merge utility for JavaScript objects
• js-yaml - YAML parser and serializer for JavaScript
• magicast - AST manipulation library for JavaScript/TypeScript
• Vite Plugin API - How Vite plugins work