Skip to content
This repository was archived by the owner on Aug 5, 2026. It is now read-only.

AGENTS.md

Latest commit

 

History

History
45 lines (39 loc) · 5.48 KB

AGENTS.md

File metadata and controls

45 lines (39 loc) · 5.48 KB
Raw

AGENTS.md

Repository Shape

  • This is a pnpm 11.0.0 workspace; install with pnpm install --frozen-lockfile to match CI. Node must be >=22; CI currently uses Node 24.8 and a pinned Foundry nightly.
  • Workspace packages are packages/*, docs, examples/**, simulation-test, and benchmark.
  • packages/core publishes the ponder npm package. Public exports start in packages/core/src/index.ts; the CLI bin starts in packages/core/src/bin/ponder.ts.
  • packages/core and packages/react build with custom build.ts scripts. packages/client, packages/utils, and packages/create-ponder build with tsup.
  • Core source uses @/* path aliases. The core build rewrites these aliases in dist/esm and dist/types, so do not replace source aliases just to satisfy package output.

Commands

  • Build publishable packages: pnpm build.
  • Lint and format use Biome: pnpm lint, pnpm format, pnpm lint:fix.
  • Root typecheck covers packages/** only: pnpm typecheck.
  • Focused package checks: pnpm --filter ponder typecheck, pnpm --filter @ponder/client typecheck, pnpm --filter @ponder/utils typecheck, pnpm --filter create-ponder typecheck.
  • Focused tests: CI=1 pnpm --filter ponder test src/path.test.ts, CI=1 pnpm --filter @ponder/client test src/index.test.ts, pnpm --filter create-ponder test.
  • Type-level Vitest suites use separate scripts where present: pnpm --filter ponder test:typecheck, pnpm --filter @ponder/client test:typecheck, pnpm --filter @ponder/react test:typecheck.
  • pnpm test runs all workspace test scripts in parallel with --no-bail; several package scripts are plain vitest, so set CI=1 for one-shot local runs and prefer --filter to avoid unrelated network-heavy suites.

Tests And Environment

  • Core Vitest setup (packages/core/vite.config.ts) caps threads at 4, loads packages/core/src/_test/setup.ts, and runs packages/core/src/_test/globalSetup.ts.
  • Core global setup generates packages/core/src/_test/generated.ts with pnpm wagmi generate if missing, then starts an Anvil proxy. Foundry/Anvil must be installed for core tests.
  • Core database tests default to in-memory PGlite. Set DATABASE_URL in packages/core/.env.local only when intentionally testing Postgres; tests create and drop vitest_* databases/roles.
  • packages/utils/src/_test/* contains live RPC-provider tests that require RPC_URL_* values from packages/utils/.env.example; avoid broad utils/root test runs unless those env vars and network access are intended.
  • simulation-test and benchmark use Bun scripts and external Postgres/RPC env from their .env.example files. Their DATABASE_URL should omit a database name; scripts append app-specific database names.

Generated Or Copied Files

  • packages/core/src/_test/generated.ts is generated by Wagmi from Foundry contracts under packages/core/src/_test/contracts/ and is ignored by Biome.
  • packages/create-ponder build copies root examples/ into packages/create-ponder/templates, excludes multi-app examples (with-nextjs, with-foundry, with-trpc, with-client, with-offchain), renames dotfiles, and blanks RPC URLs in generated _dot_env.local files.
  • Biome intentionally ignores docs/, dist/, generated folders, .ponder, cache/out directories, Solidity files, and pnpm-lock.yaml.

Docs, Examples, Releases

  • Docs are a Vocs app in docs; use pnpm --filter ponder-docs dev or pnpm --filter ponder-docs build.
  • CI separately verifies the Next.js frontend example with pnpm --filter ponder-examples-with-nextjs-frontend build after pnpm build.

Changesets

  • Changesets are fixed for ponder, create-ponder, eslint-config-ponder, @ponder/client, and @ponder/react; docs/examples are ignored. Create changesets with pnpm changeset. Public API or bug-fix PRs normally need a patch changeset.
  • Changesets has a bug for fixed packages at pre-1.0.0 versions with a minor component of 10 or greater: a minor changeset incorrectly produces 1.0.0. Manually correct the generated release PR to the next 0.x minor version (for example, 0.16.10 to 0.17.0) before merging.
  • Write changesets in the same voice as packages/core/CHANGELOG.md: concise, user-facing, past tense, and focused on observable behavior.
  • Start with the outcome, not the implementation. Prefer phrasing like "Fixed a bug that caused...", "Fixed a regression introduced in v0.16.0 that caused...", "Improved...", "Added...", "Updated...", or "Removed...".
  • Include concrete symptoms when helpful, especially exact error messages in backticks. Use patterns like "Fixed the error ..." or "that caused ...".
  • Name affected APIs, config fields, commands, packages, and options with backticks, such as ponder.config.ts, context.client, context.db, @ponder/client, p.bytes(), ordering: "omnichain", and ponder db list.
  • Use repository vocabulary consistently: Ponder, GraphQL, JSON-RPC, RPC, Postgres, PGlite, backfill, live, crash recovery, factory, and rpc cache.
  • Avoid implementation details, internal refactors, PR narration, and vague language unless the detail explains user impact. Do not write "this PR", "we", "users may notice", "various fixes", or "some improvements".
  • Keep each changeset entry narrow. If a PR includes unrelated user-facing changes, use multiple changesets or multiple short paragraphs so each changelog bullet is easy to scan.
  • For dependency-only updates, only write a custom changeset if there is a user-facing reason, such as a security patch or a fixed runtime error.