# React Native Gifted Chat

The most complete chat UI for React Native & Web. This is a TypeScript React Native component library with example applications demonstrating usage across React Native, React Native Web, and Expo platforms.

Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.

## Working Effectively

### Bootstrap and build the repository:
- `yarn install` -- NEVER CANCEL: takes 58 seconds. Set timeout to 120+ seconds.
- `yarn build` -- builds TypeScript library, takes 3 seconds. Set timeout to 30+ seconds.
- `yarn lint` -- lints source code, takes 3 seconds. Currently has warnings but no errors. Set timeout to 30+ seconds.
- `yarn test` -- NEVER CANCEL: runs Jest test suite, takes 9 seconds. Set timeout to 60+ seconds.

### Full validation before publishing:
- `yarn prepublishOnly` -- NEVER CANCEL: runs lint + test + build, takes 11 seconds total. Set timeout to 60+ seconds.

### Known Issues:
- If tests fail due to snapshot mismatches after fresh dependency install, run `yarn test -u` to update snapshots
- Snapshot tests may need updates when React Native or dependency versions change

### Example app development:
- `cd example && yarn install` -- NEVER CANCEL: takes 38 seconds. Set timeout to 90+ seconds.
- Install Expo CLI globally: `npm install -g @expo/cli` or use `npx expo` commands
- Native development: `cd example && npx expo start`
- Web development: `cd example && npx expo start --web` (requires additional dependencies)
- The example app starts Metro bundler on http://localhost:8081
- Expect dependency version warnings in offline/CI mode - these are normal

### Type checking and development:
- `yarn tsc:watch` -- runs TypeScript compiler in watch mode for development
- `yarn typecheck` -- runs TypeScript compiler to check for TS errors

## Requirements and Setup

### System Requirements:
- Node.js >= 18 (tested with 20.19.4)
- Yarn package manager 1.22.22+ (do NOT use npm for this project)
- TypeScript compiler (included in devDependencies)

### Dependencies are already installed if yarn.lock exists
The repository includes both package-lock.json and yarn.lock but ALWAYS use yarn commands, never npm commands.

## Validation

### Always run full validation before completing changes:
1. `yarn lint` -- check for code style issues (warnings are acceptable, errors are not)
2. `yarn build` -- verify TypeScript compilation succeeds
3. `yarn test` -- NEVER CANCEL: ensure all 19 test suites and 29 tests pass. Takes 31 seconds.

### Manual validation scenarios:
After making code changes, you should test basic functionality by:
1. Building the library: `yarn build` 
2. Running the test suite: `yarn test`
3. For UI changes: Start the example app with `cd example && npx expo start --web` (if web dependencies are installed) or `npx expo start` for native development
4. ALWAYS test that the TypeScript declarations in /lib are correctly generated

### Testing approach:
- All tests are located in `src/__tests__/` directory
- Tests use Jest with React Test Renderer
- Test coverage can be viewed with `yarn test:coverage`
- Snapshot tests are used extensively (27 snapshots)

## Project Structure

### Key directories:
- `/src` -- main library source code (TypeScript)
- `/lib` -- compiled JavaScript output (generated by `yarn build`, do not edit manually)  
- `/example` -- example React Native app demonstrating library usage
- `/src/__tests__` -- Jest test files
- `/.github/workflows/main.yml` -- CI/CD pipeline (tests Node 18 and 20)

### Important files:
- `package.json` -- main project configuration and scripts
- `tsconfig.json` -- TypeScript compiler configuration
- `jest.config.cjs` -- Jest test configuration
- `.eslintrc.cjs` -- ESLint linting rules
- `babel.config.cjs` -- Babel transformation configuration
- `example/package.json` -- example app dependencies

### Build output:
The `yarn build` command generates JavaScript files and TypeScript declaration files in the `/lib` directory. This directory should not be edited manually and is ignored by git but included in npm package.

## Common Tasks

### Making code changes:
1. Edit source files in `/src` directory
2. Run `yarn lint` to check style
3. Run `yarn build` to compile TypeScript
4. Run `yarn test` to verify tests pass
5. Test manually with example app if UI changes

### Adding or modifying tests:
- Tests are in `src/__tests__/` directory
- Follow existing test patterns using React Test Renderer
- Update snapshots if needed with `yarn test -u`
- Ensure all tests pass with `yarn test`

### Working with the example app:
- Example app uses Expo and demonstrates library functionality
- Install dependencies: `cd example && yarn install`
- Start development server: `npx expo start`
- For web: `npx expo start --web` (requires react-native-web and @expo/metro-runtime)

## CI/CD Integration

The repository uses GitHub Actions (`.github/workflows/main.yml`) that:
- Tests on Node.js versions 18 and 20  
- Runs `yarn install` and `yarn build`
- Build typically takes 1-2 minutes on CI

Always ensure your changes pass the full validation pipeline locally before pushing.

## Common Command Reference

### Root directory (library development):
```bash
yarn install        # Install dependencies (58 seconds)
yarn build         # Build TypeScript library (3 seconds)  
yarn lint          # Lint source code (3 seconds)
yarn test          # Run test suite (9 seconds)
yarn prepublishOnly # Full validation pipeline (11 seconds)
yarn tsc:watch     # TypeScript watch mode
```

### Example directory (app development):
```bash
cd example
yarn install       # Install example dependencies (38 seconds)
npx expo start     # Start native development server
npx expo start --web # Start web development server
```

### Time expectations (NEVER CANCEL these operations):
- yarn install: 58 seconds (root), 41 seconds (example)
- yarn build: 3 seconds
- yarn lint: 3 seconds  
- yarn test: 9 seconds (after fresh install and snapshot updates)
- yarn prepublishOnly: 11 seconds total

Always set timeouts to at least double these times to account for system variations.