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:

To learn more about the most up-to-date instructions, please refer to the guide available here.

Clone the repository

git clone git@github.com:chatwoot/chatwoot-mobile-app.git
cd chatwoot-mobile-app

Install dependencies

pnpm install

Install Expo CLI

pnpm install -g expo-cli

Environment Variables

Create your environment configuration file:

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

pnpm generate

This command generates native Android and iOS directories using Prebuild.

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

How to run the app

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

iOS Development

pnpm run:ios

Android Development

pnpm run:android

Package Installation

Please always install packages using the command npx expo install package-name instead of pnpm install package-name.

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.

# 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, 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 for Firebase, deep linking, and build setup.

Troubleshooting

Metro bundler issues

Problem: Metro bundler fails to start or bundleSolution:

# Clear cache and restart
pnpm clear
pnpm start --reset-cache

iOS build fails

Problem: iOS build or simulator issuesSolution:

Ensure Xcode is properly installed
Check iOS simulator version compatibility
Clear derived data in Xcode
Restart Metro bundler

Android build fails

Problem: Android build or emulator issuesSolution:

Verify Android Studio setup
Check SDK versions and build tools
Ensure emulator is running
Clear Gradle cache

Expo CLI issues

Problem: Expo commands failSolution:

# Update Expo CLI
npm install -g @expo/cli@latest

# Login to Expo
expo login

# Clear Expo cache
expo r -c

Contributing Guidelines

When contributing to the mobile app:

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

Getting Help

If you encounter issues:

Expo Documentation: Official Expo Docs
React Native Documentation: React Native Docs
GitHub Issues: Mobile App Issues
Community Support: Discord

Useful Resources

Expo Development: https://docs.expo.dev/
React Native: https://reactnative.dev/
EAS Build: https://docs.expo.dev/build/introduction/
EAS Submit: https://docs.expo.dev/submit/introduction/

Your Chatwoot mobile app development environment is now ready! 📱

Getting Started

Environment Setup

Project Setup

Testing

Others

Mobile App Development Setup

Setup guide for mobile app

Installation and setup

Prerequisites

Clone the repository

Install dependencies

Install Expo CLI

Environment Variables

Generate the native code

How to run the app

iOS Development

Android Development

Package Installation

Push notifications

Troubleshooting

Contributing Guidelines

Getting Help

Useful Resources

​Setup guide for mobile app

​Installation and setup

​Prerequisites

​Clone the repository

​Install dependencies

​Install Expo CLI

​Environment Variables

​Generate the native code

​How to run the app

​iOS Development

​Android Development

​Package Installation

​Push notifications

​Troubleshooting

​Contributing Guidelines

​Getting Help

​Useful Resources

Setup guide for mobile app

Installation and setup

Prerequisites

Clone the repository

Install dependencies

Install Expo CLI

Environment Variables

Generate the native code

How to run the app

iOS Development

Android Development

Package Installation

Push notifications

Troubleshooting

Contributing Guidelines

Getting Help

Useful Resources