flash-list

# flash-list

High-performance replacement for React Native's FlatList, built on recycling principles. Used by thousands of React Native apps for smooth scrolling with large datasets.

## Source Layout

- `src/` — library source code (TypeScript)
- `fixture/react-native/` — React Native test/demo app
- `dist/` — compiled output (NOT auto-rebuilt on branch switch)

## Key Constraint

`estimatedItemSize` does **NOT** exist as a prop on FlashList. Do not use it, suggest it, or add it.

## Build & Test

```bash
yarn build          # compile TypeScript to dist/
yarn test --forceExit
yarn type-check
yarn lint
```

**Important:** `dist/` is NOT rebuilt on branch switch. Always run `yarn build` after checking out a different branch.

## Node Version

Node 22.18.0

## Commit & PR Conventions

- Use conventional commits: `fix(scope): description`, `feat(scope): description`
- Scope examples: `layout`, `hooks`, `scroll`, `sticky-headers`, `recycling`, `viewability`
- Do NOT include any AI attribution (no `Co-Authored-By` AI lines, no "Generated by" or "Assisted by" text)
- PR titles should be under 70 characters and match the commit format
- Link issues with `Fixes #<number>` in the commit/PR body

## Agent PR Token (MANDATORY)

**All agent-raised PRs MUST use `SHOPIFY_GH_ACCESS_TOKEN` for PR creation.** PRs created without this token cannot be merged.

- On CI: The token is available as `$AGENT_PR_TOKEN` environment variable in agent workflows.
- When creating a PR, **always** use: `GH_TOKEN="$AGENT_PR_TOKEN" gh pr create ...`
- The default `GITHUB_TOKEN` is used for all other operations (issue comments, push, checkout). Only PR creation uses `AGENT_PR_TOKEN`.
- **Never** use bare `gh pr create` without the `GH_TOKEN="$AGENT_PR_TOKEN"` prefix — the PR will be unmergeable.

## CI Cleanup (MANDATORY)

**Before finishing on CI, kill all background processes you started** — especially Metro (`port 8081`). Leftover processes prevent the GitHub Actions job from exiting, causing it to run until timeout and waste CI minutes.

```bash
lsof -ti:8081 | xargs kill -9 2>/dev/null || true
```

## Available Skills

Skills are reusable workflows in `.claude/skills/`. Use them when relevant:

| Skill | When to use |
|---|---|
| `fix-github-issue` | Fixing a bug end-to-end: reproduce, diagnose, fix, verify on simulator, PR |
| `raise-pr` | Creating a PR with proper conventional commit format and no AI attribution |
| `review-and-test` | Reviewing a PR or branch: unit tests, type-check, lint, device testing, RTL/LTR |
| `triage-issue` | Classifying an issue (P0/P1/P2), finding duplicates, applying labels |
| `agent-device` | Interacting with iOS simulator or Android emulator (snapshot-based coordinates) |
| `upgrade-react-native` | Upgrading the fixture app's React Native version |
| `analyze-feedback` | Scanning agent workflow feedback artifacts and incorporating learnings into skills |

## Self-Learning

When you discover something important during a session — a pitfall, a non-obvious behavior, a debugging technique, or a pattern that would save time in the future — update the relevant skill file or this file so the knowledge persists.

**What to capture:**
- New pitfalls or edge cases discovered while fixing bugs
- Debugging techniques that worked (or didn't)
- Corrections to existing instructions that turned out to be wrong
- Non-obvious behaviors of FlashList, React Native, or the build system

**Where to put it:**
- Bug/fix patterns → `fix-github-issue` skill (Common Pitfalls section)
- Testing edge cases → `review-and-test` skill (Edge Cases section)
- Device interaction quirks → `agent-device` skill
- Project-wide facts → this file (`CLAUDE.md`)
- Batch analysis of agent feedback → use the `analyze-feedback` skill to scan workflow artifacts

**How:**
- Include the update in the same PR as the fix (not a separate PR)
- Keep entries concise — one line per pitfall, with enough context to be useful
- On CI, only add critical learnings (things that would cause repeated failures). Minor improvements should wait for interactive sessions.