Skip to content

agents.md

Latest commit

 

History

History
85 lines (55 loc) · 4.61 KB

agents.md

File metadata and controls

85 lines (55 loc) · 4.61 KB

AGENTS.md

This file is the operating manual for AI coding agents (Cursor, Claude Code, Codex, Aider, Devin, and others) working in this repository. Read this file before making changes.

Human contributors may also find it useful. It is written in direct, imperative style on purpose.

What this repo is

react-virtualized-diff is a React component for rendering large code/text diffs without freezing the browser. The published library lives in packages/react/. The repo is a pnpm workspace monorepo — use pnpm, not npm or yarn.

Public documentation lives in README.md and llms.txt. User-facing API changes must update both.

Project structure

packages/react/        # published npm package source — this is where most work happens
apps/demo/             # Vite demo app, used for manual testing and the hosted live demo
apps/benchmark/        # benchmark harness that produces benchmark-results/results.md
benchmark-results/     # committed benchmark output, reviewed in PRs when perf changes
.github/workflows/     # CI: runs lint + build
scripts/               # repo-level tooling

The published surface area is exactly what packages/react/ exports. Nothing under apps/ ships to npm.

Setup

pnpm install

Node and pnpm are required. Do not run npm install or yarn — it will corrupt the workspace lockfile.

Commands

All commands run from the repo root unless noted.

  • pnpm dev — start the Vite demo app against the local package source (watches and reloads)
  • pnpm build — build packages/react/
  • pnpm test — run the test suite
  • pnpm lint — run lint checks
  • pnpm benchmark — run the benchmark harness; updates benchmark-results/results.md

Before opening a PR

All of these must pass locally:

  1. pnpm lint is clean
  2. pnpm build succeeds
  3. pnpm test passes
  4. CHANGELOG.md has an entry for the change

CI also runs pnpm lint and pnpm build. Tests and CHANGELOG are checked by reviewers.

Code-change priorities

These are in priority order. If they conflict, earlier rules win.

  1. Default scope is packages/react/. Make changes here unless there is a direct reason not to. If a change requires touching apps/demo/, apps/benchmark/, or repo-level config, call that out explicitly in the PR description and explain why.

  2. Public API changes must update README.md and llms.txt. The list of props in both files is part of the public contract. Renaming a prop, changing a default, adding a prop, or removing a prop requires updating both docs in the same PR. llms.txt is how AI coding agents in downstream projects learn this library — keeping it accurate is load-bearing.

  3. Performance-sensitive changes require a benchmark comparison. "Performance-sensitive" includes anything in the render path, diff computation, virtual list integration, or memoization boundaries. Run pnpm benchmark on main first, then on your branch, and paste both relevant rows into the PR description. Do not rely on the committed results.md alone — it is a snapshot and may be stale.

  4. Every change gets a CHANGELOG.md entry. Even small fixes. Use the existing format in that file. Entries do not need to be long — one sentence is fine — but they must exist.

Code style

  • TypeScript throughout. Strict mode is on — do not introduce any to silence type errors. If a type is genuinely unknowable, use unknown and narrow.
  • Formatting is controlled by .prettierrc and .editorconfig. Do not hand-adjust whitespace; run the formatter.
  • Prefer named exports from packages/react/ entry points.
  • React hooks follow standard rules (exhaustive deps unless justified with a comment).

Things not to do without explicit instruction

  • Do not commit dist/ or other build output. .gitignore covers this; double-check before pushing.
  • Do not hand-edit pnpm-lock.yaml. If a dependency needs to change, use pnpm add / pnpm remove and commit the lockfile update.
  • Do not add new runtime dependencies without flagging the addition in the PR description. Bundle size is part of the library's value.
  • Do not bump the version in any package.json. Releases are managed separately.
  • Do not modify benchmark-results/results.md by hand — it is generated by pnpm benchmark.
  • Do not rewrite the "Why react-virtualized-diff" section of README.md or the framing of the benchmark without reviewer discussion. Those sections reflect the project's positioning.

When in doubt

Open a draft PR with a clear description of what you tried and why. The maintainer (@Zhang-JiahangH) would rather see an honest draft than a polished PR that made the wrong call.