# @pierre/diffs

An open-source library for rendering code and diffs on the web, from The Pierre Computer Co. (the team behind the Pierre git-collaboration app). It ships both high-level components and exposed internals, with syntax highlighting built on [Shiki](https://shiki.style/) for its theme and language coverage. Sibling library: [[toolbox/pierre-trees|@pierre/trees]] (file-tree rendering), in the same monorepo.

## The architectural bet

The opinionated core idea: **browsers are efficient at rendering raw HTML**, so lean into that. All the low-level APIs purely render strings — the raw HTML — which higher-order components and utilities then consume. This keeps the fast path close to the browser and lets the same primitives back both a React API and a vanilla-JS API. The higher-order components render into **Shadow DOM** with a **CSS grid** layout (style isolation from the host page, grid for the gutter/line/content columns). Most users are expected to use the high-level components; the internals are there if you want to assemble specific pieces yourself.

## What's in it

- **`FileDiff`** — render a diff two ways: from two file contents (it computes the diff), or from a patch/unified-diff. React and vanilla equivalents for everything.
- **`MultiFileDiff` / `PatchDiff` / `File`** — multi-file diffs, patch-based diffs, and plain (non-diff) file rendering with the same highlighting.
- **Virtualization** — virtual scrolling for large diffs and files, so huge changesets don't blow up the DOM.
- **Hunk separators** — built-in presets plus CSS customization hooks (with a discouraged vanilla escape hatch for custom separators).
- **Utilities** — `parseDiffFromFile`, `parsePatchFiles`, highlighter management, and accept/reject-hunk helpers.
- **Worker pool** — off-main-thread syntax highlighting via a configurable pool of workers, so highlighting large files doesn't jank the UI.
- **SSR** — server-side rendering with preload functions for instant first paint, then client hydration.

## Styling and theming

Extensive: CSS variables (the `--diffs-*` family — colors for added/modified/deleted in light and dark, fonts, gutters, scrollbar behavior), inline styles, and an unsafe CSS-injection escape hatch. Ships Pierre Light/Dark themes and supports creating and registering custom themes; Shiki underneath means broad language/theme support comes largely for free.

## Usage

```bash
npm install @pierre/diffs
```

```jsx
import { FileDiff } from "@pierre/diffs/react";

// Compute a diff from two versions of a file:
<FileDiff before={oldContents} after={newContents} lang="tsx" />

// Or render from a patch:
<PatchDiff patch={unifiedDiff} />
```

Vanilla JS has `FileDiff` / `File` classes with the same props and low-level renderers underneath.

## Notes

- Components today cover vanilla JS and React only; more frameworks "if there's demand."
- Part of the `pierrecomputer/pierre` monorepo (~5.5k★ on the whole repo, which is Pierre's broader open-source code, not just this package). Package `@pierre/diffs` is at v1.2.x and Apache-2.0.
- Docs: [diffs.com/docs](https://diffs.com/docs) (there's an `llms.txt` / `llms-full.txt` for machine reading).

## Related

- [[toolbox/pierre-trees]] — the sibling file-tree renderer, same monorepo and design language
- [[developer-icons]] — another "UI primitives for developer tools" library in the toolbox