react-git

What it does

@level0x40/react-git reads a local Git repository, extracts its source artifacts into a typed manifest, and renders them as a self-contained static site. The output is plain HTML, JSON, and assets — no server, no database, no runtime access to the original repo.

It is a thin orchestration layer over @lazarv/react-server, an open React Server Components runtime built on Vite. The build pipeline runs the production server with a streaming export hook driving renders, then writes the result to disk. Drop the artifacts on Cloudflare Pages, Netlify, GitHub Pages, S3, or any static host.

Quick start

Run from inside the repository you want to render — no arguments needed:

npx @level0x40/react-git build

The output goes to ./dist (override with --out). Drop it on any static host, or open dist/index.html directly.

For iterative work, run the dev server with hot reload:

npx @level0x40/react-git dev

Both commands accept an optional path to the repository if you'd rather run them from elsewhere:

npx @level0x40/react-git build /path/to/your/repo

Templates

Six visual styles ship in the box. Pick one with --template <name>, or stack multiple — file overrides and config merging both honour CLI order, so the last entry wins.

• defaultEditorial monospace, terra-cotta accent.
• primerGitHub-faithful Primer aesthetic.
• w3cW3C technical-report styling, navy accent.
• react-serverCompanion to react-server.dev, gold ramp.
• sketchpadHand-drawn coral-and-teal panel look.
• tuiTerminal aesthetic, ANSI palette.

# Stack two templates: a built-in for the chrome,
# a local folder for your project-specific overrides.
npx @level0x40/react-git build . \
  --template primer \
  --template ./my-overlay

Modes

Two extraction strategies, toggled with --live:

• manifest (default) — Pre-extract every commit, ref, tree, and blob into JSON shards under .react-git/cache/. Renders read from those shards. Best for production builds: deterministic, no git access at render time, cleanly cacheable.
• live — Pass --live to skip extraction and query Git directly for every render. Best for development against a moving repo, or for one-off previews.

--mode is not the mode toggle — it's forwarded to @lazarv/react-server (production/development build mode). Use --live to flip extraction strategy.

CLI reference

Every flag below is also listed in react-git --help. Flags marked passthrough are forwarded to @lazarv/react-server verbatim — most of them accept --no-<flag> to opt out (e.g. --no-compression, --no-minify).

react-git build [repo] [options]

Generates the static site to the --out directory.

Common options (build + dev)

Build-only options

Build passthrough — @lazarv/react-server

react-git dev [repo] [options]

Starts a hot-reloading dev server on http://localhost:3000.

Dev-only options

Dev passthrough — @lazarv/react-server

Examples

# Smallest invocation — build cwd to ./dist with the default template.
react-git build

# Build a sibling repo to a specific output dir.
react-git build /path/to/repo --out ./site

# W3C theme, no compression sidecars, smaller deploy.
react-git build --template w3c --no-compression

# Filter the refs that get extracted.
react-git build --include-ref 'release/*' --exclude-ref 'wip/*'

# Browse-tree pages for every extracted ref + larger /log per ref.
react-git build --browse-ref '*' --max-commits 200

# Build + deploy in one step (passthrough to react-server).
react-git build --deploy --adapter cloudflare

# Dev server bound to a non-default port + auto-open.
react-git dev --port 4000 --open

# Dev server in live mode, exposed on the LAN.
react-git dev --live --host 0.0.0.0

Data layer

The Git data extraction is a separate concern from rendering. The same code that powers the static site is exposed as a standalone library through three subpath exports — usable from any Node host, with no @lazarv/react-server runtime needed.

import { listCommits, getDiff } from "@level0x40/react-git/source";
/** @typedef {import("@level0x40/react-git/source/types").SourceCommit} Commit */

const commits = await listCommits();
const diff = await getDiff(commits[0].sha);

The public functions carry "use cache" directives that the @lazarv/react-server runtime interprets for per-request deduplication. Outside that runtime the directives are inert string statements — calls work in any Node host and just don't dedupe automatically. Wrap with your own cache for hot paths.

Configuration

Configuration comes from three layered sources, merged in this order (later wins):

1. The base config baked into @level0x40/react-git.
2. Each --template <dir>'s react-server.config.{mjs,js,ts}, in CLI order.
3. CLI flags.

Most users never write a react-server.config.* file directly — the built-in templates supply theirs. Drop a custom one inside a --template <dir> overlay only when you need to tweak Vite plugins, virtual routes, or other react-server config knobs.

Deployment

The build emits a self-contained directory. For Cloudflare Pages, Netlify, S3 + CloudFront, GitHub Pages, etc., the artifact is plain static files — copy ./dist (or whatever --out points at) to the host.

For platforms @lazarv/react-server knows how to deploy directly, use --deploy:

react-git build --deploy --adapter cloudflare
react-git build --deploy --adapter vercel
react-git build --deploy --adapter netlify

The flag is forwarded to @lazarv/react-server, which handles the platform's API/CLI interactions itself — no separate wrangler / vercel / netlify invocation needed.

Conflicts and gotchas