repository·main·Indexed 20 days ago
https://github.com/mrwangjusttodo/git-diff-viewA high-performance diff visualization library supporting React, Vue, Solid, Svelte, and CLI environments. It features syntax highlighting, split/unified views, and custom widget support. The ecosystem includes @git-diff-view/core for Git diff hunks, @git-diff-view/file for raw file comparisons, @git-diff-view/cli for terminal rendering, and highlighting options via @git-diff-view/lowlight and @git-diff-view/shiki.
When working with the scroll API, it is critical to distinguish between logical lines and visual rows:
line): The user-facing line index (1-based). This is the index used by most API methods.row): The actual terminal row after text wrapping. Internal scroll offsets are calculated using rows.A single logical line may span multiple visual rows if the content exceeds the contentWidth.
The DiffView architecture uses a flattened display sequence to manage scrolling across hunks, content, and extend lines.
Line Semantics in DiffView:
In DiffView, line refers to the 1-based index in the flattened display sequence:
mapIndex !== 0 and the hunk is visible).diffViewExtendLineHeight visual rows (used when renderExtendLine and extendData are present).Note: The first content block does not have a leading hunk line.
Rendering Behavior:
height is set: buildDiffViewScrollLayout calculates row offsets. useScrollView and getVisibleDiffScrollLines determine the visible entries (with optional clip via ScrollSlice). DiffDisplayList renders only these visible entries.height is unset: buildDiffViewScrollLayout is skipped, and DiffDisplayList iterates through all entries via iterateDiffDisplayEntries for a full render.Choose between the Shiki highlighter and the default Lowlight highlighter based on your requirements:
| Feature | @git-diff-view/lowlight | @git-diff-view/shiki |
|---|---|---|
| Default | ✅ Built-in | ❌ Separate package |
| Setup | No setup needed | Async initialization |
| Accuracy | Good | Excellent (VSCode-level) |
| Themes | highlight.js themes | VSCode themes |
| Bundle Size | Smaller | Larger |
| Performance | Synchronous | Async |
Use @git-diff-view/shiki when you need:
Use @git-diff-view/lowlight (default) when:
While @git-diff-view/lowlight is the default and lightweight option, you should consider using @git-diff-view/shiki if your project requires:
Both CodeView and DiffView support a fixed-height viewport with programmatic scrolling. To enable scroll mode, you must provide a height prop (representing the number of visual rows after line wrapping).
height: The full content is rendered (backward compatible).height: The viewport is constrained. If height is larger than the content, the viewport shrinks to the content height.width changes, the scroll offset resets to 0 because line wrapping counts change.onScrollChange provides a ScrollState object containing:
totalLines: logical line counttotalRows: visual row count after wrapviewportHeight: effective height (min of height and totalRows)scrollOffset: top visual row (0-based)startLine: first visible logical lineendLine: last visible logical linecanScrollUp: booleancanScrollDown: booleanUse a ref to control the view programmatically:
getScrollState(): Get current snapshot.scrollToTop(line): Align target logical line to viewport top.scrollToBottom(line): Align target logical line to viewport bottom.scrollUp({ unit?, step? }): Scroll up (unit is "visual" or "logical").scrollDown({ unit?, step? }): Scroll down.import { useRef } from "react";
import { CodeView, DiffView, type CodeViewRef } from "@git-diff-view/cli";
const ref = useRef<CodeViewRef>(null);
<CodeView
ref={ref}
file={file}
height={20}
width={80}
onScrollChange={(state) => console.log(state.startLine, state.endLine)}
/>;
ref.current?.scrollToTop(100);
ref.current?.scrollDown({ unit: "logical" });To avoid blocking the main thread, you can process diffs in a Web Worker or on a Node.js server. Use getBundle() to export the processed data and DiffFile.createInstance(data, bundle) on the client side to reconstruct the instance for UI components.
// Worker/Server side - generate bundle
const file = new DiffFile(/* ... */);
file.initTheme('dark');
file.init();
file.buildSplitDiffLines();
file.buildUnifiedDiffLines();
const bundle = file.getBundle();
// Send bundle to main thread/client
// Main thread/Client side - reconstruct
import { DiffFile } from "@git-diff-view/core";
const mergedFile = DiffFile.createInstance(data, bundle);
// Use with UI components
<DiffView diffFile={mergedFile} />In CodeView, the line refers to the source file line number (File.rawFile, ranging from 1 to rawLength).
Rendering Behavior:
height is set: The component builds a full ScrollLayout using useMemo. The useScrollView hook maintains the scrollOffset and slices the layout.rows. The final output is a single sliced ANSI <Text> component rendered inside a <Box height={height} overflow="hidden">.height is unset: All rows are rendered without slicing.Choose the appropriate package based on your input data:
@git-diff-view/core when you have Git diff hunks (standard git output).@git-diff-view/file when you have raw file contents and want to compare them directly without git..vue imports by default, you must use vue-tsc instead of the standard tsc CLI for type checking in your project. For editor-level type awareness, ensure the TypeScript Vue Plugin (Volar) is installed.To set up the SolidJS example project, install the necessary dependencies using your preferred package manager.
$ npm install # or pnpm install or yarn installYou can choose between two CSS import options depending on your project's styling setup:
import "@git-diff-view/react/styles/diff-view.css";import "@git-diff-view/react/styles/diff-view-pure.css";// Default styles with Tailwind
import "@git-diff-view/react/styles/diff-view.css";
// Pure CSS (no Tailwind conflicts)
import "@git-diff-view/react/styles/diff-view-pure.css";Install the Solid component package using your preferred package manager.
npm install @git-diff-view/solid
# or
pnpm add @git-diff-view/solid
# or
yarn add @git-diff-view/solid