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):

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):

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.