git-json-resolver-semver

Semver-aware plugin for git-json-resolver — resolve JSON version conflicts (e.g., package.json) via semantic-version strategies.

Strategies (this release):

• semver-max → pick the higher version
• semver-min → pick the lower version
• semver-ours → prefer ours if valid, else (optionally) prefer valid theirs
• semver-theirs → prefer theirs if valid, else (optionally) prefer valid ours

✨ Features

• Avoid manual conflict resolution in package.json
• Small & tree-shakable (0 runtime dependencies)
• Works with direct import or dynamic plugin loading
• TypeScript types included

Star the repo if it saved your merge. And and also share it with your friends.

📦 Install

pnpm add git-json-resolver-semver

or

npm install git-json-resolver-semver

or

yarn add git-json-resolver-semver

Peer dependencies:

pnpm install git-json-resolver

🚀 Usage

1. Direct Import

import createSemverPlugin, { semverMax } from "git-json-resolver-semver";
import { resolveConflicts } from "git-json-resolver";

// Option 1: Use factory function with custom config
const plugin = createSemverPlugin({
  strict: false,
  fallback: "ours",
});

await resolveConflicts({
  customStrategies: plugin.strategies,
  rules: {
    "dependencies.react": ["semver-max"],
    "devDependencies.vitest": ["semver-min"],
  },
});

// Option 2: Use individual strategy exports - not scoped @see migration guide for more details
await resolveConflicts({
  customStrategies: {
    "semver-max": semverMax,
  },
  rules: {
    "dependencies.react": ["semver-max"],
    "devDependencies.vitest": ["semver-min"],
  },
});

2. Dynamic Loading

{
  "plugins": ["git-json-resolver-semver"],
  "rules": {
    "dependencies.react": ["semver-max"],
    "devDependencies.vitest": ["semver-min"]
  }
}

or TypeScript Config

// git-json-resolver.config.ts
import type { Config } from "git-json-resolver";

const config: Config = {
  plugins: ["git-json-resolver-semver"],
  rules: {
    "dependencies.react": ["semver-max"],
    "devDependencies.vitest": ["semver-min"],
  },
};

export default config;

⚙️ Configuration

Factory Pattern (Recommended)

import createSemverPlugin from "git-json-resolver-semver";

const plugin = createSemverPlugin({
  strict: true, // Use validateStrict for exact semver only
  preferValid: true, // Prefer valid semver when only one side is valid
  fallback: "continue", // Behavior when both sides invalid
  preferRange: false, // Future: merge into semver ranges
  workspacePattern: "", // Pattern for workspace rules
});

Global Configuration

import { init } from "git-json-resolver-semver";

init({
  strict: false, // Allow prereleases and ranges
  fallback: "ours",
});

Behavior Notes

• strict mode uses validateStrict - only accepts x.y.z format
• preferValid returns the valid side when the other is invalid
• fallback controls behavior when neither side is valid
• Version prefixes like ^1.2.3 are automatically handled

⚙️ Strategies

| Strategy | Behavior | Example (ours vs theirs) | Result | | --------------- | --------------------------------------------------------------------- | ---------------------------- | ------- | | semver-max | Picks the higher valid semver | 1.2.3 vs 1.3.0 | 1.3.0 | | semver-min | Picks the lower valid semver | 2.0.0 vs 2.1.0 | 2.0.0 | | semver-ours | Picks ours if valid semver, else apply preferValid / fallback | 1.2.3 vs banana | 1.2.3 | | semver-theirs | Picks theirs if valid semver, else apply preferValid / fallback | foo vs 2.0.0 | 2.0.0 |

🙏 Acknowledgments

• git-json-resolver for the plugin system
• compare-versions for lightweight semver checks

License

This library is licensed under the MPL-2.0 open-source license.

Please enroll in our courses or sponsor our work.