Skip to main content

​
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:
NameDescriptionDefault ValueRequired
EXPO_PUBLIC_CHATWOOT_WEBSITE_TOKENWeb widget token for in-app support-No
EXPO_PUBLIC_CHATWOOT_BASE_URLSelf-hosted installation URLhttps://app.chatwoot.comYes
EXPO_PUBLIC_JUNE_SDK_KEYJune analytics SDK key-No
EXPO_PUBLIC_MINIMUM_CHATWOOT_VERSIONMinimum supported Chatwoot version-Yes
EXPO_PUBLIC_SENTRY_DSNSentry DSN URL for error reporting-No
EXPO_PUBLIC_PROJECT_IDExpo project identifier-Yes
EXPO_PUBLIC_APP_SLUGApplication slug for Expo-Yes
EXPO_PUBLIC_SENTRY_PROJECT_NAMEProject name in Sentry-No
EXPO_PUBLIC_SENTRY_ORG_NAMEOrganization name in Sentry-No
EXPO_PUBLIC_IOS_GOOGLE_SERVICES_FILEPath to iOS Google Services config file-No
EXPO_PUBLIC_ANDROID_GOOGLE_SERVICES_FILEPath to Android Google Services config file-No
EXPO_APPLE_IDApple Developer account ID-No
EXPO_APPLE_TEAM_IDApple Developer team ID-No
EXPO_STORYBOOK_ENABLEDEnable/disable StorybookfalseNo

​
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

Problem: Metro bundler fails to start or bundleSolution:
# Clear cache and restart
pnpm clear
pnpm start --reset-cache
Problem: iOS build or simulator issuesSolution:
  • Ensure Xcode is properly installed
  • Check iOS simulator version compatibility
  • Clear derived data in Xcode
  • Restart Metro bundler
Problem: Android build or emulator issuesSolution:
  • Verify Android Studio setup
  • Check SDK versions and build tools
  • Ensure emulator is running
  • Clear Gradle cache
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:
  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:

​
Useful Resources

Your Chatwoot mobile app development environment is now ready! 📱