Edit on GitHub

Run the Mattermost mobile app

We provide a set of scripts to help you run the app for the different platforms that are executed with npm:

  • npm start: Start the React Native packager. The packager has to be running in order to build the JavaScript code that powers the app.
  • npm run android: Compile and run the mobile app on Android.
  • npm run ios: Compile and run the mobile app on iOS.

The above commands are shortcuts for the react-native CLI. You can append -- --help to the above commands to see available options, for example:

npm run android -- --help

Make sure you are adding -- before the options you want to include or run the react-native CLI directly:

npx react-native run-android --help

Run on a device 

By default, running the app will launch an Android emulator (if you created one) or an iOS simulator.

If you want to test the performance of the app or if you want to make a contribution it is always a good idea to run the app on an actual device. This will let you ensure that the app is working correctly and in a performant way before submitting a pull request.

To be able to run the app on an Android device you’ll need to follow these steps:

  1. Enable debugging over USB

    Most Android devices can only install and run apps downloaded from Google Play by default. In order to be able to install the Mattermost Mobile app in the device during development you will need to enable USB Debugging on your device in the Developer options menu by going to Settings > About phone and then tap the Build number row at the bottom seven times, then go back to Settings > Developer options and enable USB debugging.

  2. Plug in your device via USB

    Plug in your Android device in any available USB port in your development machine (try to avoid hubs and plug it directly into your computer) and check that your device is properly connecting to ADB (Android Debug Bridge) by running adb devices.

    $ adb devices
    List of devices attached
    42006fb3e4fb25b8    device

    If you see device in the right column that means that the device is connected. You can have multiple devices attached and the app will be deployed to all of them.

  3. Compile and run

    With your device connected to the USB port execute the following in your command prompt to install and launch the app on the device:

    npm run android

To be able to run the app on an iOS device you’ll need to have Xcode installed on a Mac computer and follow this steps:

  1. Get an Apple Developer account

    The apps that run on an iOS device must be signed. To sign it, you’ll need a set of provisioning profiles. If you already have an Apple Developer account enrolled in the Apple Developer program you can skip this step. If you don’t have an account yet you’ll need to create one and enroll in the Apple Developer Program.

  2. Open the project in Xcode

    Navigate to the ios folder in your mattermost-mobile project, then open the file Mattermost.xcworkspace in Xcode.

  3. Configure code signing and capabilities

    Select the Mattermost project in the Xcode Project Navigator, then select the Mattermost target. Look for the Signing & Capabilities tab.

    • Go to the Signing section and make sure your Apple developer account or team is selected under the Team dropdown and change the Bundle Identifier. Xcode will register your provisioning profiles in your account for the Bundle Identifier you’ve entered if it doesn’t exist.
    • Go to the App Groups section and change the App Groups. Xcode will register your AppGroupId and update the provision profile.
    • Go to the iCloud section and change the Containers. Xcode will register your iCloud container and update the provision profile.
    • Go to the Keychain Sharing section and change the Keychain Groups. Xcode will register your Keychain access groups and update the provision profile.
  1. Compile and run

    Plug in your iOS device in any available USB port in your development computer.

    If everything is set up correctly, your device will be listed as the build target in the Xcode toolbar, and it will also appear in the Devices Pane (2). You can press the Build and run button (R) or select Run from the Product menu to run the app.


    As an alternative you can select the targeted device by opening the Product menu in Xcode menu bar, then go to Destination and look for your device to select from the list.

Did you find what you were looking for?

Thank you! We appreciate your feedback.

Tell us more

Your feedback helps us improve the Mattermost developer documentation.

Have a feature request? Share it here.

Having issues? Join our Community server.