Skip to content

AGENTS.md

Latest commit

 

History

History
175 lines (136 loc) · 7.09 KB

AGENTS.md

File metadata and controls

175 lines (136 loc) · 7.09 KB

AGENTS.md — AI Agent Instructions

This file provides context for AI agents (Cursor, Claude, Copilot, etc.) working on this repository. Read it in full before making any changes.

Project Overview

react-native-typescript-library-starter is a React Native TypeScript library starter template. It is NOT an application — it is a publishable npm package used as a starting point for building React Native component/hook libraries.

  • Build tool: react-native-builder-bob (outputs CJS + ESM + TypeScript declarations)
  • Testing: Jest + @testing-library/react-native
  • Language: TypeScript (strict mode, no any)
  • Linting: ESLint v8 + Prettier
  • CI: GitHub Actions (typecheck + lint + test + build)

Directory Map

react-native-typescript-library-starter/
├── src/                          # ALL library source code lives here
│   ├── index.ts                  # Public API — only export from here
│   ├── components/
│   │   └── MyComponent/
│   │       ├── MyComponent.tsx        # Implementation
│   │       ├── MyComponent.types.ts   # Props interface
│   │       └── index.ts               # Barrel export
│   ├── hooks/
│   │   └── useMyHook.ts          # Custom hook with TSDoc
│   ├── types/
│   │   └── index.ts              # Shared utility types
│   └── __tests__/
│       ├── MyComponent.test.tsx
│       └── useMyHook.test.ts
├── lib/                          # GENERATED by bob — do NOT edit manually
│   ├── commonjs/                 # CJS output
│   ├── module/                   # ESM output
│   └── typescript/               # .d.ts declarations
├── scripts/
│   └── terminal/
│       ├── lint.mjs              # Colored ESLint runner
│       └── prettier.mjs          # Colored Prettier runner
├── .github/
│   └── workflows/
│       ├── ci.yml                # Runs on PR: typecheck + lint + test + build
│       └── release.yml           # Runs on push to main: release pipeline
├── .husky/                       # Git hooks (pre-commit, commit-msg)
├── AGENTS.md                     # This file
├── CONTRIBUTING.md
├── CHANGELOG.md
├── README.md
├── package.json                  # bob config, jest config, lint-staged config
├── tsconfig.json                 # Base TypeScript config
├── tsconfig.build.json           # bob-specific build config
├── babel.config.js               # metro-react-native-babel-preset (for Jest)
├── .eslintrc.js
├── .prettierrc
└── .commitlintrc.json

Commands

All commands should be run from the repository root.

Command Description
npm run setup Interactive wizard — configure name, author, repo URLs
npm install Install all dependencies (also runs husky via prepare)
npm run build Build library to lib/ via bob
npm run typecheck Type-check without emitting files
npm run lint Run ESLint with colored output
npm run lint:ci Run ESLint without spinner (for CI)
npm run prettier Format code with colored output
npm run prettier:ci Check formatting without spinner (for CI)
npm test Run Jest tests
npm run test:watch Run Jest in watch mode
npm run test:coverage Run Jest with coverage report

Conventions

TypeScript

  • Strict mode is enabled ("strict": true). No any, no ts-ignore without a comment explaining why.
  • Use type for type aliases and interface for object shapes.
  • Always use import type for type-only imports.
  • Path alias @/* maps to src/*.

Components

  • One component per folder under src/components/.
  • File naming: MyComponent.tsx (implementation), MyComponent.types.ts (props), index.ts (barrel).
  • Props interface must be named <ComponentName>Props and exported from the barrel.
  • All props must have TSDoc comments with @example tags for non-trivial props.
  • Use StyleSheet.create() — no inline style objects.
  • Forward testID and derive child testIDs as ${testID}-<part>.

Hooks

  • One hook per file under src/hooks/.
  • Export the hook as a named export (not default).
  • Export the options interface as Use<HookName>Options.
  • Export the return interface as Use<HookName>Return.
  • All hooks must have full TSDoc with @param, @returns, and @example.

Public API

  • Only add exports to src/index.ts — this is the package entry point.
  • Export both the value and its types from src/index.ts.
  • Never import from lib/ — always from src/.

Commits

Follow Conventional Commits. Allowed types: feat, fix, perf, refactor, style, test, docs, ci, chore, revert.

Examples:

feat: add PressableCard component
fix: correct button accessibility role
test: add edge cases for useMyHook
docs: update README with new API

Testing

  • Test files live in src/__tests__/.
  • File names match the source: MyComponent.test.tsx, useMyHook.test.ts.
  • Use @testing-library/react-native for component tests (render, fireEvent, getByTestId).
  • Use renderHook + act for hook tests.
  • Group tests with describe blocks: describe("rendering"), describe("interactions"), describe("accessibility").
  • Coverage thresholds: 70% branches, 80% functions/lines/statements.

What NOT to Do

  • Do NOT edit files in lib/ — they are generated by bob build.
  • Do NOT use require() — use ES module import.
  • Do NOT add peerDependencies as dependencies or devDependencies without justification.
  • Do NOT export internal helpers from src/index.ts — only public API.
  • Do NOT disable ESLint rules without an explanatory comment.
  • Do NOT add console.log to source files.
  • Do NOT use default exports for hooks — named exports only.
  • Do NOT skip tests when adding new features.

Adding a New Component

  1. Create src/components/NewComponent/NewComponent.types.ts — props interface with full TSDoc.
  2. Create src/components/NewComponent/NewComponent.tsx — implementation.
  3. Create src/components/NewComponent/index.ts — barrel.
  4. Create src/components/NewComponent/__tests__/NewComponent.test.tsx — or add to src/__tests__/.
  5. Add exports to src/index.ts.

Adding a New Hook

  1. Create src/hooks/useNewHook.ts with options, return interface, and implementation.
  2. Add exports to src/index.ts.
  3. Add tests to src/__tests__/useNewHook.test.ts.

Environment Notes

  • Node.js: LTS (>=18)
  • React Native: >=0.70.0 (peer dependency)
  • React: >=17.0.0 (peer dependency)
  • Package manager: npm