CoMapeo Mobile

The next version of Mapeo Mobile

Getting started

1. Clone repository

   git clone https://github.com/digidem/comapeo-mobile.git

2. Set up the development environment

   1. Install Node, ideally through a proper node version manager such as nvm, fnm, asdf, or mise

      • This project uses Node v20 with npm v10

   2. Follow the React Native instructions for setting up the development environment: https://reactnative.dev/docs/environment-setup

      • Note that Java 17 is the minimum version required for this project.

      • When setting up the Android-specific tooling, you will also need to install the Android NDK. This can be installed using Android Studio by going to the SDK Tools tab in the SDK Manager. This project uses NDK 25.1.8937393.

   3. Copy the .env.template file to a file called .env. Replace any placeholder <replace_me> values with the relevant ones:

      MAPBOX_ACCESS_TOKEN: a Mapbox access token. If you do not have access to a Mapbox account, reach out to the maintainers about getting access to an access token.

      MAPBOX_DOWNLOAD_TOKEN: a Mapbox secret token. This is unfortunately required to install the necessary Mapbox Android SDK components used by @rnmapbox/maps@10 when building the app (more info here). If you do not have access to a Mapbox account, reach out to the maintainers about getting access to a secret token.

      COMAPEO_METRICS_URL: URL pointing to a hosted CoMapeo metrics server. Reach out to the maintainers about getting access to this credential. COMAPEO_METRICS_API_KEY: API key needed for accessing a CoMapeo metrics server. Reach out to the maintainers about getting access to this credential.

3. Run the app locally

   1. Install dependencies

      • This project requires the following system dependencies. Make sure they are available on your PATH.

        • curl
        • tar

      • Install NPM-based project dependencies

        npm install

   2. Generate the native code

      • This project uses Expo Prebuild for generating the relevant native code. If you update app.json or app.config.js, or install/update any dependencies that provide native code, you should run the following command to make sure the project is up-to-date:

      npx expo prebuild

      If you have made any manual changes to the generated directories (e.g. android/ or ios/), you may need to specify the --clean flag with the command.

   3. Start the Metro bundler process

      npm start

      Leave this running in a separate terminal window.

   4. Build and run the app (Android)

      • For this project, using a physical device is more convenient and reliable to work with. It is recommended that you follow React Native's setup instructions for running an app on a device.

      • Run the following command to build the backend and then build and run the Android app:

        npm run android

        If you do not need to rebuild the backend on subsequent runs (e.g. no changes in the src/backend/ directory), you can use the following command instead:

        npm run android-no-backend-rebuild

E2E Testing

This project is tested with BrowserStack.