> ## Documentation Index
> Fetch the complete documentation index at: https://developers.chatwoot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile App Development Setup

> Setup guide for Chatwoot mobile app development

# Setup guide for mobile app

Complete guide to setting up the Chatwoot mobile app for development and contribution.

## Installation and setup

### Prerequisites

Before starting, ensure you have the following installed:

* [Node.js](https://nodejs.org/en/download/) (Latest LTS version)
* [React Native CLI](https://reactnative.dev/docs/environment-setup)
* [Expo CLI](https://docs.expo.dev/get-started/installation/)
* [Expo Account](https://expo.dev/signup)

<Note>
  To learn more about the most up-to-date instructions, please refer to the guide available [here](https://docs.expo.dev/get-started/set-up-your-environment/).
</Note>

### Clone the repository

```bash theme={null}
git clone git@github.com:chatwoot/chatwoot-mobile-app.git
cd chatwoot-mobile-app
```

### Install dependencies

```bash theme={null}
pnpm install
```

### Install Expo CLI

```bash theme={null}
pnpm install -g expo-cli
```

## Environment Variables

Create your environment configuration file:

```bash theme={null}
cp .env.example .env
```

Configure the following environment variables:

| Name                                          | Description                                 | Default Value                                        | Required |
| --------------------------------------------- | ------------------------------------------- | ---------------------------------------------------- | -------- |
| EXPO\_PUBLIC\_CHATWOOT\_WEBSITE\_TOKEN        | Web widget token for in-app support         | -                                                    | No       |
| EXPO\_PUBLIC\_CHATWOOT\_BASE\_URL             | Self-hosted installation URL                | [https://app.chatwoot.com](https://app.chatwoot.com) | Yes      |
| EXPO\_PUBLIC\_JUNE\_SDK\_KEY                  | June analytics SDK key                      | -                                                    | No       |
| EXPO\_PUBLIC\_MINIMUM\_CHATWOOT\_VERSION      | Minimum supported Chatwoot version          | -                                                    | Yes      |
| EXPO\_PUBLIC\_SENTRY\_DSN                     | Sentry DSN URL for error reporting          | -                                                    | No       |
| EXPO\_PUBLIC\_PROJECT\_ID                     | Expo project identifier                     | -                                                    | Yes      |
| EXPO\_PUBLIC\_APP\_SLUG                       | Application slug for Expo                   | -                                                    | Yes      |
| EXPO\_PUBLIC\_SENTRY\_PROJECT\_NAME           | Project name in Sentry                      | -                                                    | No       |
| EXPO\_PUBLIC\_SENTRY\_ORG\_NAME               | Organization name in Sentry                 | -                                                    | No       |
| EXPO\_PUBLIC\_IOS\_GOOGLE\_SERVICES\_FILE     | Path to iOS Google Services config file     | -                                                    | No       |
| EXPO\_PUBLIC\_ANDROID\_GOOGLE\_SERVICES\_FILE | Path to Android Google Services config file | -                                                    | No       |
| EXPO\_APPLE\_ID                               | Apple Developer account ID                  | -                                                    | No       |
| EXPO\_APPLE\_TEAM\_ID                         | Apple Developer team ID                     | -                                                    | No       |
| EXPO\_STORYBOOK\_ENABLED                      | Enable/disable Storybook                    | false                                                | No       |

## Generate the native code

```bash theme={null}
pnpm generate
```

This command generates native Android and iOS directories using [Prebuild](https://docs.expo.dev/workflow/continuous-native-generation/).

<Warning>
  You need to run pre-build if you add a new native dependency to your project or change the project configuration in Expo app config (app.config.ts).
</Warning>

## How to run the app

Connect your iPhone/Android device and run the following command to install the app on your device.

### iOS Development

```bash theme={null}
pnpm run:ios
```

### Android Development

```bash theme={null}
pnpm run:android
```

## Package Installation

<Warning>
  Please always install packages using the command `npx expo install package-name` instead of `pnpm install package-name`.
</Warning>

This is crucial for native dependencies because Expo will automatically install the correct compatible version, while pnpm/yarn/npm may install the latest version, which may not be compatible.

```bash theme={null}
# Correct way to install packages
npx expo install package-name

# Incorrect way (may cause compatibility issues)
pnpm install package-name
```

## Push notifications

If you are using the community edition of Chatwoot with the [official mobile app](https://www.chatwoot.com/mobile-apps), push notifications work out of the box with no additional configuration.

If you are building a custom-branded app, refer to the [custom mobile app guide](/self-hosted/custom-mobile-app) for Firebase, deep linking, and build setup.

## Troubleshooting

<Accordion title="Metro bundler issues">
  **Problem**: Metro bundler fails to start or bundle

  **Solution**:

  ```bash theme={null}
  # Clear cache and restart
  pnpm clear
  pnpm start --reset-cache
  ```
</Accordion>

<Accordion title="iOS build fails">
  **Problem**: iOS build or simulator issues

  **Solution**:

  * Ensure Xcode is properly installed
  * Check iOS simulator version compatibility
  * Clear derived data in Xcode
  * Restart Metro bundler
</Accordion>

<Accordion title="Android build fails">
  **Problem**: Android build or emulator issues

  **Solution**:

  * Verify Android Studio setup
  * Check SDK versions and build tools
  * Ensure emulator is running
  * Clear Gradle cache
</Accordion>

<Accordion title="Expo CLI issues">
  **Problem**: Expo commands fail

  **Solution**:

  ```bash theme={null}
  # Update Expo CLI
  npm install -g @expo/cli@latest

  # Login to Expo
  expo login

  # Clear Expo cache
  expo r -c
  ```
</Accordion>

## Contributing Guidelines

When contributing to the mobile app:

1. **Follow coding standards**: Use ESLint and Prettier configurations
2. **Write tests**: Include unit tests for new features
3. **Test on both platforms**: Ensure iOS and Android compatibility
4. **Update documentation**: Document new features and changes
5. **Check performance**: Monitor app performance impact

## Getting Help

If you encounter issues:

* **Expo Documentation**: [Official Expo Docs](https://docs.expo.dev/)
* **React Native Documentation**: [React Native Docs](https://reactnative.dev/docs/getting-started)
* **GitHub Issues**: [Mobile App Issues](https://github.com/chatwoot/chatwoot-mobile-app/issues)
* **Community Support**: [Discord](https://discord.com/invite/cJXdrwS)

## Useful Resources

* **Expo Development**: [https://docs.expo.dev/](https://docs.expo.dev/)
* **React Native**: [https://reactnative.dev/](https://reactnative.dev/)
* **EAS Build**: [https://docs.expo.dev/build/introduction/](https://docs.expo.dev/build/introduction/)
* **EAS Submit**: [https://docs.expo.dev/submit/introduction/](https://docs.expo.dev/submit/introduction/)

***

Your Chatwoot mobile app development environment is now ready! 📱