AGENTS.md · tamagui/tamagui

Sections

1. Finish what you start, then merge it back
2. Worktrees: create in one place, leave none behind
3. Before you call anything done, run these two at the REPO ROOT
4. Running Tests
5. Commit Message Conventions
6. iOS Development
7. tamagui.dev
8. Fast upstream releases

First lines (shown under the repo's MIT license)

# Tamagui — agent operating contract

`CLAUDE.md` is a symlink to this file, so Claude, Codex, and every other agent
read the same rules. Put durable, repo-wide agent guidance here.

## Finish what you start, then merge it back

The most common failure here is stopping early: a fix left on a branch, a
migration written but never applied, a "critical, will do next" item dropped.
Don't do that. If you were asked to do something, it is not done until:

- it is committed, pushed, validated, and **merged back to `main`** (or a PR is
  opened and driven to merge) — "I left it on a branch" / "I prepared the SQL"
  is not done; feature release PRs wait for owner review before merging;
- it is **validated at the layer it changes**: typecheck/build for code, a real
  request or Playwright run for site behavior, an applied-and-verified query for
  a DB/RLS change. "Should work" is not validation;
- for security/payments work especially, the loop is closed end to end — a
  documented finding with no shipped, deployed fix counts as no fix.

Keep going until the requested outcome is real. Continuing beats reporting. The
only hard stops are the externally-irreversible ones — publishing/releasing to
npm, force-pushing, rotating credentials, or changing prod infra (Cloudflare,
DNS, Railway settings): pause and confirm for those, and hand them back with the
exact steps when they block you. Everything else, finish it.

## Worktrees: create in one place, leave none behind

Worktrees pile up. Measured 2026-09-01: the fleet held about 470 linked
worktrees across five machines, most abandoned with no live session and nothing
unpushed. Rules:

- Create worktrees only under `~/.worktrees/tamagui-<slug>`, from a freshly
  fetched base branch. Never in `/tmp`, a scratchpad, or inside the repo.
- The session that creates a worktree owns it. When the task ends (merged,
  handed off, or abandoned) either `git worktree remove <path>` from the primary
  checkout, or leave it clean with every commit pushed to its branch, and say
  which in your final report.
- Uncommitted work in a worktree at session end is lost work. Commit it to the
  branch and push, as a `wip:` commit if unfinished, before you stop.
- A long task in the shared checkout that will not be committable for hours
  belongs in a worktree so a co-tenant push cannot publish it half done.
- Managers prune without asking: any worktree with no live owner, a clean tree,
  and a HEAD reachable from `origin` is removed. `tm drift` is the audit.

## Before you call anything done, run these two at the REPO ROOT

```sh
bun run lint     # oxfmt --check && oxlint. oxlint alone misses formatting
bun run check    # deps, unused, tamagui, references, paths, web-types, lsp-pins
```

Your package's own suite cannot see either one, and neither can `bun run
typecheck`. Both are whole-workspace questions, so a change that is green in
every test you ran can still be red here:

- `bun run check` runs `knip`, which sees across package boundaries. It catches
  an unreferenced file, a dependency nothing imports, and a second way to invoke
  something that already has a declared script. A CI step written as
  `bun scripts/whatever.ts --check` when the package already declares
  `check:whatever` is a real finding, not a style nit.
- `oxfmt` is separate from `oxlint`. A file committed unformatted passes lint
  locally if you only ran the linter.

Both were learned the expensive way: two of three CI cycles on the v3-beta wave
B tip went red on exactly these, after every lane had reported its own suites
green.

In a shared checkout, both commands see the WHOLE worktree, including other
agents' uncommitted and untracked files, so they can fail on a file you never
opened. Read which files are named. Fix the ones that are yours; for anyone
else's, say so in your report and leave them alone. Formatting a co-tenant's
in-progress file is worse than the failure, because your edit lands inside their
uncommitted work where they cannot see it. The rule asks that YOUR change not
break the workspace, not that a tree five agents are editing is spotless.

---

Please read ./CONTRIBUTING.md as well

Note you need to re-build packages (`bun run build` in the package directory) as you change them, unless you or someone is running a `bun run watch` at root.

FOR LONG RUNNNING DEBUGGING run `bun run watch` in the background its faster and rebuilds all packages.

keep commits to one line, add a trailing "Fixes #" if associated with a GH issue, and start with a convential commit style - UNLESS its a change that shouldn't go into the changelog, in those cases you can do things like `docs: ` or `site: `.

# Tamagui Testing Guide

## Running Tests

### Kitchen Sink Tests

The kitchen-sink package contains the main integration tests for Tamagui components. To run these tests:

1. **Start the web server** (in the background):

   ```bash
   cd code/kitchen-sink
   bun run start:web
   ```

   To open a specific test case in the browser:

   ```bash
   open "http://localhost:7979/?test=YourTestCaseName"
   ```

   Test case names match the file names in `code/kitchen-sink/src/usecases/` (e.g., `SelectFocusScopeCase`).

   To open a component demo:

   ```bash
   open "http://localhost:7979/?demo=Select"
   ```

   Demo names match files in `code/demos/src/` without the `Demo` suffix (e.g., `Select` for `SelectDemo.tsx`).

2. **Run all web tests** with different animation drivers:

   ```bash
   bun run test:web
   ```

   This uses `run-tests-parallel.ts` which first runs `default` + `webkit` projects sequentially, then runs the three animated web driver projects (`css`, `reanimated`, `motion`) in parallel against a single shared dev server.

3. **Run tests with a specific animation driver**:

   ```bash
   # Using env var + playwright --project flag
   cd code/kitchen-sink
   NODE_ENV=test TAMAGUI_TEST_ANIMATION_DRIVER=css npx playwright test --project=animated-css

   # Available projects: animated-css, animated-reanimated, animated-motion
   ```

4. **Run a specific test file**:

   ```bash
   # Using playwright directly
   cd code/kitchen-sink
   npx playwright test tests/PopoverFocusScope.test.tsx

   # Or with a specific driver
   NODE_ENV=test TAMAGUI_TEST_ANIMATION_DRIVER=css npx playwright test tests/YourTest.animated.test.tsx --project=animated-css
   ```

5. **Debug tests**:
   ```bash
   bun run test:web:debug
   # or
   npx playwright test --debug
   ```

### Test Structure

Tests are located in `code/kitchen-sink/tests/` and follow these naming conventions:

- `ComponentName.test.tsx` - Standard tests that run ONCE with the default animation driver
- `ComponentName.animated.test.tsx` - Animation-dependent tests that run with all web animation drivers (css, reanimated, motion)