Skip to content

Commit 983ecea

Browse files
mayank1513mayank1513
committed
Apply changesets and update CHANGELOG [skip ci]
1 parent 49a9622 commit 983ecea

File tree

1 file changed

+79
-72
lines changed

1 file changed

+79
-72
lines changed

‎lib/README.md‎

Lines changed: 79 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -7,25 +7,26 @@
77
[![Downloads](https://img.jsdelivr.com/img.shields.io/npm/d18m/git-json-resolver.svg)](https://www.npmjs.com/package/git-json-resolver)
88
![npm bundle size](https://img.shields.io/bundlephobia/minzip/git-json-resolver)
99

10-
Git Json Resolver is a comprehensive library designed to unlock the full potential of React 18 server components. It provides customizable loading animation components and a fullscreen loader container, seamlessly integrating with React and Next.js.
10+
A Git-aware conflict resolver for **JSON-first structured data**.
1111

12-
✅ Fully Treeshakable (import from `git-json-resolver/client/loader-container`)
12+
## Why?
1313

14-
✅ Fully TypeScript Supported
14+
- Git merge conflicts in structured files (JSON, YAML, XML, TOML) are painful.
15+
- Manual resolution is error-prone, time-consuming, and breaks CI/CD pipelines.
16+
- `git-json-resolver` automates conflict handling with **configurable strategies**.
17+
- Non-JSON formats are internally normalized to JSON → resolved → converted back.
1518

16-
✅ Leverages the power of React 18 Server components
19+
## Features
1720

18-
✅ Compatible with all React 18 build systems/tools/frameworks
21+
- ⚡ **Primary focus on JSON** (first-class support)
22+
- 🔄 **YAML, XML, TOML** supported via conversion
23+
- 🧩 **Rule-based strategies** (per path/pattern)
24+
- 🗂️ Handles small configs to **huge repos** (optimizations built-in)
25+
- 🔌 **Pluggable matcher** abstraction (picomatch, micromatch supported out of the box with peerDependency)
26+
- 🛠️ Configurable trade-offs for **speed vs. memory**
27+
- 🗃️ **Planned**: extend configuration to use **different strategies per file** (ideas and edge cases welcome!)
1928

20-
✅ Documented with [Typedoc](https://react18-tools.github.io/git-json-resolver) ([Docs](https://react18-tools.github.io/git-json-resolver))
21-
22-
✅ Examples for Next.js, and Vite
23-
24-
> <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 20px"/> Star [this repository](https://github.com/react18-tools/git-json-resolver) and share it with your friends.
25-
26-
## Getting Started
27-
28-
### Installation
29+
## Installation
2930

3031
```bash
3132
pnpm add git-json-resolver
@@ -43,92 +44,98 @@ npm install git-json-resolver
4344
yarn add git-json-resolver
4445
```
4546

46-
## Want Lite Version? [![npm bundle size](https://img.shields.io/bundlephobia/minzip/git-json-resolver-lite)](https://www.npmjs.com/package/git-json-resolver-lite) [![Version](https://img.shields.io/npm/v/git-json-resolver-lite.svg?colorB=green)](https://www.npmjs.com/package/git-json-resolver-lite) [![Downloads](https://img.jsdelivr.com/img.shields.io/npm/d18m/git-json-resolver-lite.svg)](https://www.npmjs.com/package/git-json-resolver-lite)
47+
## Quick Start
4748

48-
```bash
49-
pnpm add git-json-resolver-lite
50-
```
51-
52-
**or**
49+
Add a custom merge driver to your Git config:
5350

5451
```bash
55-
npm install git-json-resolver-lite
52+
git config merge.json-resolver.name "Custom JSON merge driver"
53+
git config merge.json-resolver.driver "npx git-json-resolver %A %O %B"
5654
```
5755

58-
**or**
56+
Update `.gitattributes` to use it for JSON files:
5957

60-
```bash
61-
yarn add git-json-resolver-lite
58+
```gitattributes
59+
*.json merge=json-resolver
6260
```
6361

64-
> You need `r18gs` as a peer-dependency
62+
## Example Config
63+
64+
```ts
65+
import { resolveConflicts } from "git-json-resolver";
66+
67+
const result = resolveConflicts({
68+
filePath: "package.json",
69+
rules: [
70+
{ pattern: "dependencies.*", strategy: "ours" },
71+
{ pattern: "version", strategy: "theirs", important: true },
72+
{ pattern: "scripts.build", strategy: "manual" },
73+
],
74+
matcher: "picomatch", // default
75+
optimize: {
76+
cacheMatchers: true,
77+
streamMode: false, // set true for very large repos
78+
},
79+
});
80+
```
6581

66-
### Import Styles
82+
### Upcoming: File-Specific Strategies
6783

68-
You can import styles globally or within specific components.
84+
We are exploring the ability to define **per-file strategy sets** in config, e.g.:
6985

70-
```css
71-
/* globals.css */
72-
@import "git-json-resolver/dist";
86+
```ts
87+
rulesByFile: {
88+
"package.json": { version: ["theirs"], dependencies: ["ours"] },
89+
"*.config.json": { "*": ["merge"] },
90+
},
7391
```
7492

75-
```tsx
76-
// layout.tsx
77-
import "git-json-resolver/dist/index.css";
78-
```
93+
This raises interesting questions/edge cases:
7994

80-
For selective imports:
95+
- How to merge file-level vs. global rules?
96+
- Should `include/exclude` still apply if a file is explicitly listed?
97+
- Should conflicting rules between file + global fall back to default strategy or error?
8198

82-
```css
83-
/* globals.css */
84-
@import "git-json-resolver/dist/client"; /** required if you are using LoaderContainer */
85-
@import "git-json-resolver/dist/server/bars/bars1";
86-
```
99+
We welcome ideas & edge cases here!
87100

88-
### Usage
101+
## Supported Strategies
89102

90-
Using loaders is straightforward.
103+
- **ours** → take current branch value
104+
- **theirs** → take incoming branch value
105+
- **manual** → mark for human resolution
106+
- **drop** → remove the key entirely
107+
- **custom** → user-defined resolver function
91108

92-
```tsx
93-
import { Bars1 } from "git-json-resolver/dist/server/bars/bars1";
109+
## Supported Formats
94110

95-
export default function MyComponent() {
96-
return someCondition ? <Bars1 /> : <>Something else...</>;
97-
}
98-
```
111+
- **JSON** (native)
112+
- **YAML, XML, TOML** → converted to JSON → resolved → converted back
99113

100-
For detailed API and options, refer to [the API documentation](https://react18-tools.github.io/git-json-resolver).
114+
## Performance & Optimization
101115

102-
**Using LoaderContainer**
116+
- **Matcher caching** for repeated patterns
117+
- **Streaming mode** for very large repos (low memory footprint)
118+
- Trade-offs are configurable via `optimize` field
103119

104-
`LoaderContainer` is a fullscreen component. You can add this component directly in your layout and then use `useLoader` hook to toggle its visibility.
120+
## Roadmap
105121

106-
```tsx
107-
// layout.tsx
108-
<LoaderContainer />
109-
...
110-
```
122+
- [ ] Richer strategies via plugins (e.g., semantic version resolver)
123+
- [ ] CLI UX improvements
124+
- [ ] Pluggable format converters customizations
125+
- [ ] VSCode integration for previewing merge resolutions
126+
- [ ] **Per-file strategies support** (current RFC)
111127

112-
```tsx
113-
// some other page or component
114-
import { useLoader } from "git-json-resolver/dist/hooks";
115-
116-
export default MyComponent() {
117-
const { setLoading } = useLoader();
118-
useCallback(()=>{
119-
setLoading(true);
120-
...do some work
121-
setLoading(false);
122-
}, [])
123-
...
124-
}
125-
```
128+
## Contributing
126129

127-
## License
130+
Contributions welcome 🙌
128131

129-
This library is licensed under the MPL-2.0 open-source license.
132+
- Fork, branch, PR — with tests (`vitest` required)
133+
- Docs live in `libDocs/` (tutorials, guides, deep dives)
134+
- API reference generated into `docs/` via TypeDoc
130135

136+
## License
131137

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

133140
> <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 20px"/> Please enroll in [our courses](https://mayank-chaudhari.vercel.app/courses) or [sponsor](https://github.com/sponsors/mayank1513) our work.
134141

0 commit comments

Comments
 (0)