From 20f5c9c71583710f48398c4d70d4297ad0c5e792 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kamil=20Str=C3=B3=C5=BC?= Date: Fri, 19 Sep 2025 11:58:02 +0200 Subject: [PATCH 01/11] docs: clarify mobile setup steps MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kamil Stróż --- README.md | 65 ++++++++++++++++++++++++++----------------------------- 1 file changed, 31 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 0d0d0dbceee8..0b6cdff6d660 100644 --- a/README.md +++ b/README.md @@ -63,39 +63,7 @@ If you're using another operating system, you will need to ensure `mkcert` is in * To run the **development web app**: `npm run web` * Changes applied to Javascript will be applied automatically via WebPack as configured in `webpack.dev.ts` -## Running the iOS app 📱 -For an M1 Mac, read this [SO](https://stackoverflow.com/questions/64901180/how-to-run-cocoapods-on-apple-silicon-m1) for installing cocoapods. - -* If you haven't already, install Xcode tools and make sure to install the optional "iOS Platform" package as well. This installation may take awhile. - * After installation, check in System Settings that there's no update for Xcode. Otherwise, you may encounter issues later that don't explain that you solve them by updating Xcode. -* Install project gems, including cocoapods, using bundler to ensure everyone uses the same versions. In the project root, run: `bundle install` - * If you get the error `Could not find 'bundler'`, install the bundler gem first: `gem install bundler` and try again. - * If you are using MacOS and get the error `Gem::FilePermissionError` when trying to install the bundler gem, you're likely using system Ruby, which requires administrator permission to modify. To get around this, install another version of Ruby with a version manager like [rbenv](https://github.com/rbenv/rbenv#installation). -* Before installing iOS dependencies, you need to obtain a token from Mapbox to download their SDKs. Please run `npm run configure-mapbox` and follow the instructions. - * For help with MapBox token, you can see [this Slack thread](https://expensify.slack.com/archives/C01GTK53T8Q/p1692740856745279?thread_ts=1692322511.804599&cid=C01GTK53T8Q) -* To install the iOS dependencies, run: `npm install && npm run pod-install` -* If you are an Expensify employee and want to point the emulator to your local VM, follow [this](https://stackoverflow.com/c/expensify/questions/7699) -* To run a on a **Development Simulator**: `npm run ios` -* Changes applied to Javascript will be applied automatically, any changes to native code will require a recompile - -If you want to run the app on an actual physical iOS device, please follow the instructions [here](https://github.com/Expensify/App/blob/main/contributingGuides/HOW_TO_BUILD_APP_ON_PHYSICAL_IOS_DEVICE.md). - -## Running the Android app 🤖 -* Before installing Android dependencies, you need to obtain a token from Mapbox to download their SDKs. Please run `npm run configure-mapbox` and follow the instructions. If you already did this step for iOS, there is no need to repeat this step. -* Go through the official React-Native instructions on [this page](https://reactnative.dev/docs/environment-setup?guide=native&platform=android) to start running the app on android. -* If you are an Expensify employee and want to point the emulator to your local VM, follow [this](https://stackoverflow.com/c/expensify/questions/7699) -* To run a on a **Development Emulator**: `npm run android` -* Changes applied to Javascript will be applied automatically, any changes to native code will require a recompile - -### Enabling prebuilt `react-native` artifacts on Android -#### Disabling build from source - -By default, `react-native` is built from source when building the Android app. However, you can enable prebuilt artifacts to speed up the build process: - - - Open `android/gradle.properties` (for Standalone NewDot) or `Mobile-Expensify/Android/gradle.properties` (for HybridApp) - - Set `patchedArtifacts.forceBuildFromSource=false` - -#### Configuring GitHub CLI +## Enabling prebuilt `react-native` artifacts To use prebuilt artifacts, you need to have GitHub CLI installed and configured: @@ -121,7 +89,36 @@ To use prebuilt artifacts, you need to have GitHub CLI installed and configured: ``` You should see a message confirming you are authenticated with your GitHub account. -After completing these steps, you should be able to build Android apps with prebuilt `react-native` artifacts. +After completing these steps, you should be able to build both mobile platform apps using the prebuilt react-native artifacts. + +### Troubleshooting +* If fetching cached builds for mobile fails, check whether both workflows succeeded. If they didn’t, the failure will prevent Rock from fetching the cached builds. + +## Running the iOS app 📱 +For an M1 Mac, read this [SO](https://stackoverflow.com/questions/64901180/how-to-run-cocoapods-on-apple-silicon-m1) for installing cocoapods. + +* If you haven't already, install Xcode tools and make sure to install the optional "iOS Platform" package as well. This installation may take awhile. + * After installation, check in System Settings that there's no update for Xcode. Otherwise, you may encounter issues later that don't explain that you solve them by updating Xcode. +* Install project gems, including cocoapods, using bundler to ensure everyone uses the same versions. In the project root, run: `bundle install` + * If you get the error `Could not find 'bundler'`, install the bundler gem first: `gem install bundler` and try again. + * If you are using MacOS and get the error `Gem::FilePermissionError` when trying to install the bundler gem, you're likely using system Ruby, which requires administrator permission to modify. To get around this, install another version of Ruby with a version manager like [rbenv](https://github.com/rbenv/rbenv#installation). +* Before installing iOS dependencies, you need to obtain a token from Mapbox to download their SDKs. Please run `npm run configure-mapbox` and follow the instructions. + * For help with MapBox token, you can see [this Slack thread](https://expensify.slack.com/archives/C01GTK53T8Q/p1692740856745279?thread_ts=1692322511.804599&cid=C01GTK53T8Q) +* To install the dependencies, run: `npm install` +* If you are an Expensify employee and want to point the emulator to your local VM, follow [this](https://stackoverflow.com/c/expensify/questions/7699) +* To run a on a **Development Simulator**: `npm run ios` +* Changes applied to Javascript will be applied automatically, any changes to native code will require a recompile + +If you want to run the app on an actual physical iOS device, please follow the instructions [here](https://github.com/Expensify/App/blob/main/contributingGuides/HOW_TO_BUILD_APP_ON_PHYSICAL_IOS_DEVICE.md). + +## Running the Android app 🤖 +* Before installing Android dependencies, you need to obtain a token from Mapbox to download their SDKs. Please run `npm run configure-mapbox` and follow the instructions. If you already did this step for iOS, there is no need to repeat this step. +* Go through the official React-Native instructions on [this page](https://reactnative.dev/docs/environment-setup?guide=native&platform=android) to start running the app on android. +* If you are an Expensify employee and want to point the emulator to your local VM, follow [this](https://stackoverflow.com/c/expensify/questions/7699) +* To run a on a **Development Emulator**: `npm run android` +* Changes applied to Javascript will be applied automatically, any changes to native code will require a recompile + + ## Running the MacOS desktop app 🖥 * To run the **Development app**, run: `npm run desktop`, this will start a new Electron process running on your MacOS desktop in the `dist/Mac` folder. From 2980986096477bfea5fe4636ef9e4145411f6fe7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kamil=20Str=C3=B3=C5=BC?= Date: Fri, 19 Sep 2025 14:03:28 +0200 Subject: [PATCH 02/11] docs: remove obsolete steps --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 0b6cdff6d660..d39ca919f5bb 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,7 @@ If you're using another operating system, you will need to ensure `mkcert` is in ## Enabling prebuilt `react-native` artifacts -To use prebuilt artifacts, you need to have GitHub CLI installed and configured: +To use prebuilt artifacts for mobile applications, you need to have GitHub CLI installed and configured: 1. Install GitHub CLI by following the instructions from [cli.github.com](https://cli.github.com/) @@ -89,6 +89,8 @@ To use prebuilt artifacts, you need to have GitHub CLI installed and configured: ``` You should see a message confirming you are authenticated with your GitHub account. +5. Add `GITHUB_TOKEN` to `.env` file with your generated token + After completing these steps, you should be able to build both mobile platform apps using the prebuilt react-native artifacts. ### Troubleshooting @@ -99,9 +101,6 @@ For an M1 Mac, read this [SO](https://stackoverflow.com/questions/64901180/how-t * If you haven't already, install Xcode tools and make sure to install the optional "iOS Platform" package as well. This installation may take awhile. * After installation, check in System Settings that there's no update for Xcode. Otherwise, you may encounter issues later that don't explain that you solve them by updating Xcode. -* Install project gems, including cocoapods, using bundler to ensure everyone uses the same versions. In the project root, run: `bundle install` - * If you get the error `Could not find 'bundler'`, install the bundler gem first: `gem install bundler` and try again. - * If you are using MacOS and get the error `Gem::FilePermissionError` when trying to install the bundler gem, you're likely using system Ruby, which requires administrator permission to modify. To get around this, install another version of Ruby with a version manager like [rbenv](https://github.com/rbenv/rbenv#installation). * Before installing iOS dependencies, you need to obtain a token from Mapbox to download their SDKs. Please run `npm run configure-mapbox` and follow the instructions. * For help with MapBox token, you can see [this Slack thread](https://expensify.slack.com/archives/C01GTK53T8Q/p1692740856745279?thread_ts=1692322511.804599&cid=C01GTK53T8Q) * To install the dependencies, run: `npm install` @@ -114,6 +113,7 @@ If you want to run the app on an actual physical iOS device, please follow the i ## Running the Android app 🤖 * Before installing Android dependencies, you need to obtain a token from Mapbox to download their SDKs. Please run `npm run configure-mapbox` and follow the instructions. If you already did this step for iOS, there is no need to repeat this step. * Go through the official React-Native instructions on [this page](https://reactnative.dev/docs/environment-setup?guide=native&platform=android) to start running the app on android. +* To install dependencies, run `npm install` if you haven’t already done so during the iOS setup process. * If you are an Expensify employee and want to point the emulator to your local VM, follow [this](https://stackoverflow.com/c/expensify/questions/7699) * To run a on a **Development Emulator**: `npm run android` * Changes applied to Javascript will be applied automatically, any changes to native code will require a recompile From fc38898afc65995a7bdf70ade0bdeb0d8c862395 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kamil=20Str=C3=B3=C5=BC?= Date: Wed, 24 Sep 2025 12:57:59 +0200 Subject: [PATCH 03/11] docs: split mobile setup into two parts 1st for remote builds and 2nd for manual build --- README.md | 37 +++++++++++++++++++++++++++++++------ 1 file changed, 31 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index d39ca919f5bb..e7b03e40fe64 100644 --- a/README.md +++ b/README.md @@ -63,9 +63,15 @@ If you're using another operating system, you will need to ensure `mkcert` is in * To run the **development web app**: `npm run web` * Changes applied to Javascript will be applied automatically via WebPack as configured in `webpack.dev.ts` -## Enabling prebuilt `react-native` artifacts +## Running the mobile application using Rock 🪨 -To use prebuilt artifacts for mobile applications, you need to have GitHub CLI installed and configured: +This project leverages [Rock](rockjs.dev) to manage builds remotely. By storing the complete build on a remote server, Rock.js eliminates the need for local builds and enables streamlined setup through automated downloads. + +The following steps describe how to configure the project to fully utilize Rock. + +### Configuring GitHub CLI + +To use rock remote builds for mobile applications, you need to have GitHub CLI installed and configured: 1. Install GitHub CLI by following the instructions from [cli.github.com](https://cli.github.com/) @@ -91,12 +97,25 @@ To use prebuilt artifacts for mobile applications, you need to have GitHub CLI i 5. Add `GITHUB_TOKEN` to `.env` file with your generated token -After completing these steps, you should be able to build both mobile platform apps using the prebuilt react-native artifacts. +### Running the mobile application 📱 +* To install project dependencies run: `npm install` +* To run application on a **Development Simulator**: `npm run ios` or `npm run android` + +After completing these steps, you should be able to start both mobile platform apps using the remote build. ### Troubleshooting -* If fetching cached builds for mobile fails, check whether both workflows succeeded. If they didn’t, the failure will prevent Rock from fetching the cached builds. +* If fetching cached builds for mobile fails, verify that both workflows in the GitHub repository have completed successfully. If they did not, Rock will be unable to fetch the cached builds. -## Running the iOS app 📱 +* If you’re still encountering errors, you can try running: + - `git clean -fdx` + - `git clean -fdx ./Mobile-Expensify` + - You may also want to reinstall node_modules. + +* In the event of workflow failures, it is recommended to have the option to manually build the application. The following steps will cover the manual build process. + +## Running the mobile application using manual builds + +### Running the iOS app 📱 For an M1 Mac, read this [SO](https://stackoverflow.com/questions/64901180/how-to-run-cocoapods-on-apple-silicon-m1) for installing cocoapods. * If you haven't already, install Xcode tools and make sure to install the optional "iOS Platform" package as well. This installation may take awhile. @@ -110,7 +129,7 @@ For an M1 Mac, read this [SO](https://stackoverflow.com/questions/64901180/how-t If you want to run the app on an actual physical iOS device, please follow the instructions [here](https://github.com/Expensify/App/blob/main/contributingGuides/HOW_TO_BUILD_APP_ON_PHYSICAL_IOS_DEVICE.md). -## Running the Android app 🤖 +### Running the Android app 🤖 * Before installing Android dependencies, you need to obtain a token from Mapbox to download their SDKs. Please run `npm run configure-mapbox` and follow the instructions. If you already did this step for iOS, there is no need to repeat this step. * Go through the official React-Native instructions on [this page](https://reactnative.dev/docs/environment-setup?guide=native&platform=android) to start running the app on android. * To install dependencies, run `npm install` if you haven’t already done so during the iOS setup process. @@ -118,7 +137,13 @@ If you want to run the app on an actual physical iOS device, please follow the i * To run a on a **Development Emulator**: `npm run android` * Changes applied to Javascript will be applied automatically, any changes to native code will require a recompile +### Enabling prebuilt `react-native` artifacts on Android +#### Disabling build from source + +By default, `react-native` is built from source when building the Android app. However, you can enable prebuilt artifacts to speed up the build process: + - Open `android/gradle.properties` (for Standalone NewDot) or `Mobile-Expensify/Android/gradle.properties` (for HybridApp) + - Set `patchedArtifacts.forceBuildFromSource=false` ## Running the MacOS desktop app 🖥 * To run the **Development app**, run: `npm run desktop`, this will start a new Electron process running on your MacOS desktop in the `dist/Mac` folder. From 299f7acde0d486e4af0459eda3b8ed80416375eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kamil=20Str=C3=B3=C5=BC?= Date: Wed, 24 Sep 2025 13:51:05 +0200 Subject: [PATCH 04/11] docs: added command for running metro server --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index e7b03e40fe64..140a24c29292 100644 --- a/README.md +++ b/README.md @@ -99,6 +99,7 @@ To use rock remote builds for mobile applications, you need to have GitHub CLI i ### Running the mobile application 📱 * To install project dependencies run: `npm install` +* To start metro server run: `npm run start` * To run application on a **Development Simulator**: `npm run ios` or `npm run android` After completing these steps, you should be able to start both mobile platform apps using the remote build. @@ -123,6 +124,7 @@ For an M1 Mac, read this [SO](https://stackoverflow.com/questions/64901180/how-t * Before installing iOS dependencies, you need to obtain a token from Mapbox to download their SDKs. Please run `npm run configure-mapbox` and follow the instructions. * For help with MapBox token, you can see [this Slack thread](https://expensify.slack.com/archives/C01GTK53T8Q/p1692740856745279?thread_ts=1692322511.804599&cid=C01GTK53T8Q) * To install the dependencies, run: `npm install` +* To start metro server run: `npm run start` * If you are an Expensify employee and want to point the emulator to your local VM, follow [this](https://stackoverflow.com/c/expensify/questions/7699) * To run a on a **Development Simulator**: `npm run ios` * Changes applied to Javascript will be applied automatically, any changes to native code will require a recompile @@ -133,6 +135,7 @@ If you want to run the app on an actual physical iOS device, please follow the i * Before installing Android dependencies, you need to obtain a token from Mapbox to download their SDKs. Please run `npm run configure-mapbox` and follow the instructions. If you already did this step for iOS, there is no need to repeat this step. * Go through the official React-Native instructions on [this page](https://reactnative.dev/docs/environment-setup?guide=native&platform=android) to start running the app on android. * To install dependencies, run `npm install` if you haven’t already done so during the iOS setup process. +* To start metro server run: `npm run start` * If you are an Expensify employee and want to point the emulator to your local VM, follow [this](https://stackoverflow.com/c/expensify/questions/7699) * To run a on a **Development Emulator**: `npm run android` * Changes applied to Javascript will be applied automatically, any changes to native code will require a recompile From 80c08b3572093baa40cfcd2003b342235039c7c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kamil=20Str=C3=B3=C5=BC?= Date: Thu, 25 Sep 2025 12:20:10 +0200 Subject: [PATCH 05/11] docs: split github steps for rock and manual builds --- README.md | 53 ++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 36 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 140a24c29292..095c5f3d20c2 100644 --- a/README.md +++ b/README.md @@ -65,17 +65,15 @@ If you're using another operating system, you will need to ensure `mkcert` is in ## Running the mobile application using Rock 🪨 -This project leverages [Rock](rockjs.dev) to manage builds remotely. By storing the complete build on a remote server, Rock.js eliminates the need for local builds and enables streamlined setup through automated downloads. +This project leverages [Rock](rockjs.dev) to manage builds. With Rock, the build is downloaded from a remote server first, and if a matching remote build cannot be found, it falls back to building locally. By storing the complete build on a remote server, Rock.js minimizes the need for local builds and enables streamlined setup through automated downloads. The following steps describe how to configure the project to fully utilize Rock. -### Configuring GitHub CLI +### Generating GitHub Personal Access Token -To use rock remote builds for mobile applications, you need to have GitHub CLI installed and configured: +To use rock remote builds for mobile applications, you need to have GitHub Personal Access Token in your `.env` file: -1. Install GitHub CLI by following the instructions from [cli.github.com](https://cli.github.com/) - -2. Create a GitHub Personal Access Token: +1. Create a GitHub Personal Access Token: - Go to [GitHub Settings > Developer Settings > Personal Access Tokens](https://github.com/settings/tokens) - Click "Generate new token (classic)" - Select the following scopes: @@ -83,19 +81,10 @@ To use rock remote builds for mobile applications, you need to have GitHub CLI i - `read:org` - `gist` - `read:packages` - - Copy the generated token -3. Login to GitHub CLI: - ```bash - echo "YOUR_TOKEN" | gh auth login --with-token - ``` -4. Verify the login was successful: - ```bash - gh auth status - ``` - You should see a message confirming you are authenticated with your GitHub account. +2. Copy the generated token -5. Add `GITHUB_TOKEN` to `.env` file with your generated token +3. Add `GITHUB_TOKEN` to `.env` file with your generated token ### Running the mobile application 📱 * To install project dependencies run: `npm install` @@ -148,6 +137,36 @@ By default, `react-native` is built from source when building the Android app. H - Open `android/gradle.properties` (for Standalone NewDot) or `Mobile-Expensify/Android/gradle.properties` (for HybridApp) - Set `patchedArtifacts.forceBuildFromSource=false` +#### Configuring GitHub CLI + +To use prebuilt artifacts, you need to have GitHub CLI installed and configured: + +1. Install GitHub CLI by following the instructions from [cli.github.com](https://cli.github.com/) + +2. Create a GitHub Personal Access Token. (If you already completed this step during the Rock setup, there is no need to repeat it): + - Go to [GitHub Settings > Developer Settings > Personal Access Tokens](https://github.com/settings/tokens) + - Click "Generate new token (classic)" + - Select the following scopes: + - `repo` + - `read:org` + - `gist` + - `read:packages` + +3. Copy the generated token + +4. Login to GitHub CLI: + ```bash + echo "YOUR_TOKEN" | gh auth login --with-token + ``` + +5. Verify the login was successful: + ```bash + gh auth status + ``` + You should see a message confirming you are authenticated with your GitHub account. + +After completing these steps, you should be able to build Android apps with prebuilt `react-native` artifacts. + ## Running the MacOS desktop app 🖥 * To run the **Development app**, run: `npm run desktop`, this will start a new Electron process running on your MacOS desktop in the `dist/Mac` folder. From 29627a34da895789666eaaac709c9ec4b28bbcfe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kamil=20Str=C3=B3=C5=BC?= Date: Fri, 26 Sep 2025 11:50:09 +0200 Subject: [PATCH 06/11] docs: changes after review --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 095c5f3d20c2..9654d5c0db63 100644 --- a/README.md +++ b/README.md @@ -65,22 +65,21 @@ If you're using another operating system, you will need to ensure `mkcert` is in ## Running the mobile application using Rock 🪨 -This project leverages [Rock](rockjs.dev) to manage builds. With Rock, the build is downloaded from a remote server first, and if a matching remote build cannot be found, it falls back to building locally. By storing the complete build on a remote server, Rock.js minimizes the need for local builds and enables streamlined setup through automated downloads. +This project uses [Rock](https://rockjs.dev/) to manage native builds. Rather than compiling native code locally when running commands like `npm run ios` or `npm run android`, Rock first attempts to download remote builds (artifacts prebuilt on CI) from a server. If a matching remote build isn’t available, it automatically falls back to building locally. + +By storing complete native build artifacts remotely, Rock reduces the need for local compilation and simplifies setup through automated downloads. The following steps describe how to configure the project to fully utilize Rock. ### Generating GitHub Personal Access Token -To use rock remote builds for mobile applications, you need to have GitHub Personal Access Token in your `.env` file: +To take advantage of remote builds, setup your GitHub Personal Access Token (PAT) in your `.env` file: 1. Create a GitHub Personal Access Token: - Go to [GitHub Settings > Developer Settings > Personal Access Tokens](https://github.com/settings/tokens) - Click "Generate new token (classic)" - - Select the following scopes: + - Select the following scope: - `repo` - - `read:org` - - `gist` - - `read:packages` 2. Copy the generated token @@ -89,6 +88,7 @@ To use rock remote builds for mobile applications, you need to have GitHub Perso ### Running the mobile application 📱 * To install project dependencies run: `npm install` * To start metro server run: `npm run start` +**Note:** For now this is a required step — metro needs to be called manually in a separate terminal. * To run application on a **Development Simulator**: `npm run ios` or `npm run android` After completing these steps, you should be able to start both mobile platform apps using the remote build. @@ -143,7 +143,7 @@ To use prebuilt artifacts, you need to have GitHub CLI installed and configured: 1. Install GitHub CLI by following the instructions from [cli.github.com](https://cli.github.com/) -2. Create a GitHub Personal Access Token. (If you already completed this step during the Rock setup, there is no need to repeat it): +2. Create a GitHub Personal Access Token: - Go to [GitHub Settings > Developer Settings > Personal Access Tokens](https://github.com/settings/tokens) - Click "Generate new token (classic)" - Select the following scopes: From 4d094216e228f2eb53ba60d618bc681d2ca303e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kamil=20Str=C3=B3=C5=BC?= Date: Fri, 26 Sep 2025 14:15:41 +0200 Subject: [PATCH 07/11] docs: improve troubleshooting for rock --- README.md | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 32efc15057e4..c0497cfed112 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,8 @@ This project uses [Rock](https://rockjs.dev/) to manage native builds. Rather th By storing complete native build artifacts remotely, Rock reduces the need for local compilation and simplifies setup through automated downloads. +**Note:** Any changes to files involved in generating a fingerprint (e.g., `package.json`) will trigger a local build. + The following steps describe how to configure the project to fully utilize Rock. ### Generating GitHub Personal Access Token @@ -85,12 +87,28 @@ To take advantage of remote builds, setup your GitHub Personal Access Token (PAT After completing these steps, you should be able to start both mobile platform apps using the remote build. ### Troubleshooting -* If fetching cached builds for mobile fails, verify that both workflows in the GitHub repository have completed successfully. If they did not, Rock will be unable to fetch the cached builds. +* Try re-installing dependencies: + - `npm run i-standalone` for the standalone app + - `npm install` for the hybrid app + +* Try running `npm run ios` or `npm run android` again * If you’re still encountering errors, you can try running: - - `git clean -fdx` - - `git clean -fdx ./Mobile-Expensify` - - You may also want to reinstall node_modules. + - `git clean -fdx ios/` when running iOS + - `git clean -fdx android/` when running Android + - `git clean -fdx ./Mobile-Expensify` when running hybrid app + +* Then try running `npm run ios` or `npm run android` again + +* If the issue persists, verify that both workflows in the GitHub repository have completed successfully: + - [iOS builds](https://github.com/Expensify/App/actions/workflows/remote-build-ios.yml) + - [Android builds](https://github.com/Expensify/App/actions/workflows/remote-build-android.yml) + If the workflows are still running, open them and verify they match your fingerprint. Once complete, Rock should download the remote build. If not, check whether the last main commit hash merged into your branch has the same fingerprint as yours. + + If the fingerprints do not match, run: + - `npx rock fingerprint -p ios --verbose` for iOS + - `npx rock fingerprint -p android --verbose` for Android + Compare the results with the GitHub Actions output to see which files have different fingerprints. * In the event of workflow failures, it is recommended to have the option to manually build the application. The following steps will cover the manual build process. From 0e99a9804a03af1fe0a2d040f2cb7f511a84d5e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kamil=20Str=C3=B3=C5=BC?= Date: Mon, 29 Sep 2025 11:24:24 +0200 Subject: [PATCH 08/11] docs: added more info about running standalone version --- README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c0497cfed112..0c3e27b4b430 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,9 @@ To take advantage of remote builds, setup your GitHub Personal Access Token (PAT * To install project dependencies run: `npm install` * To start metro server run: `npm run start` **Note:** For now this is a required step — metro needs to be called manually in a separate terminal. -* To run application on a **Development Simulator**: `npm run ios` or `npm run android` +* To run application on a **Development Simulator**: + - For iOS `npm run ios-standalone` or `npm run ios` (hybrid app) + - For Android `npm run android-standalone` or `npm run android` (hybrid app) After completing these steps, you should be able to start both mobile platform apps using the remote build. @@ -91,14 +93,18 @@ After completing these steps, you should be able to start both mobile platform a - `npm run i-standalone` for the standalone app - `npm install` for the hybrid app -* Try running `npm run ios` or `npm run android` again +* Try running: + - For iOS `npm run ios-standalone` or `npm run ios` (hybrid app) + - For Android `npm run android-standalone` or `npm run android` (hybrid app) * If you’re still encountering errors, you can try running: - `git clean -fdx ios/` when running iOS - `git clean -fdx android/` when running Android - `git clean -fdx ./Mobile-Expensify` when running hybrid app -* Then try running `npm run ios` or `npm run android` again +* Then try running again: + - For iOS `npm run ios-standalone` or `npm run ios` (hybrid app) + - For Android `npm run android-standalone` or `npm run android` (hybrid app) * If the issue persists, verify that both workflows in the GitHub repository have completed successfully: - [iOS builds](https://github.com/Expensify/App/actions/workflows/remote-build-ios.yml) From 23c4c7b9c5f041a59ee22e3d4c7db1ecd63413ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kamil=20Str=C3=B3=C5=BC?= Date: Mon, 29 Sep 2025 15:01:38 +0200 Subject: [PATCH 09/11] docs: added troubleshooting intro --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 0c3e27b4b430..9af4a3dc0c60 100644 --- a/README.md +++ b/README.md @@ -89,6 +89,8 @@ To take advantage of remote builds, setup your GitHub Personal Access Token (PAT After completing these steps, you should be able to start both mobile platform apps using the remote build. ### Troubleshooting +If you haven't done any intentional edits outside of `src/` (like adding new dependencies) but your app is still running into a full build, remember that it's way easier to debug and address a remote cache miss rather than any compilation error. + * Try re-installing dependencies: - `npm run i-standalone` for the standalone app - `npm install` for the hybrid app From ecacc7c741eea7c1bbfe41bf885e9997fb1fe287 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kamil=20Str=C3=B3=C5=BC?= Date: Wed, 8 Oct 2025 11:37:14 +0200 Subject: [PATCH 10/11] docs: adapt to new readme structure --- contributingGuides/SETUP_ANDROID.md | 66 ++++++++++++++++++++++++++++- contributingGuides/SETUP_IOS.md | 64 +++++++++++++++++++++++++++- 2 files changed, 127 insertions(+), 3 deletions(-) diff --git a/contributingGuides/SETUP_ANDROID.md b/contributingGuides/SETUP_ANDROID.md index 90bdbf9c3e1e..a6e2a7ef04d0 100644 --- a/contributingGuides/SETUP_ANDROID.md +++ b/contributingGuides/SETUP_ANDROID.md @@ -1,6 +1,68 @@ # Android Setup Instructions -## Prerequisites +## Running the mobile application using Rock 🪨 + +This project uses [Rock](https://rockjs.dev/) to manage native builds. Rather than compiling native code locally when running commands like `npm run android`, Rock first attempts to download remote builds (artifacts prebuilt on CI) from a server. If a matching remote build isn’t available, it automatically falls back to building locally. + +By storing complete native build artifacts remotely, Rock reduces the need for local compilation and simplifies setup through automated downloads. + +**Note:** Any changes to files involved in generating a fingerprint (e.g., `package.json`) will trigger a local build. + +The following steps describe how to configure the project to fully utilize Rock. + +### Generating GitHub Personal Access Token + +To take advantage of remote builds, setup your GitHub Personal Access Token (PAT) in your `.env` file: + +1. Create a GitHub Personal Access Token: + - Go to [GitHub Settings > Developer Settings > Personal Access Tokens](https://github.com/settings/tokens) + - Click "Generate new token (classic)" + - Select the following scope: + - `repo` + - Copy the generated token + +2. Add `GITHUB_TOKEN` to `.env` file with your generated token + +### Running the mobile application 📱 +* To install project dependencies run: `npm install` +* To start metro server run: `npm run start` +**Note:** For now this is a required step — metro needs to be called manually in a separate terminal. +* To run application on a **Development Simulator**: + - For standalone `npm run android-standalone` + - For hybrid app `npm run android` + +After completing these steps, you should be able to start both mobile platform apps using the remote build. + +### Troubleshooting +If you haven't done any intentional edits outside of `src/` (like adding new dependencies) but your app is still running into a full build, remember that it's way easier to debug and address a remote cache miss rather than any compilation error. + +* Try re-installing dependencies: + - `npm run i-standalone` for the standalone app + - `npm install` for the hybrid app + +* Try running: + - For standalone `npm run android-standalone` + - For hybrid app `npm run android` + +* If you’re still encountering errors, you can try running: + - `git clean -fdx android/` when running standalone app + - `git clean -fdx ./Mobile-Expensify` when running hybrid app + +* Then try running again: + - For standalone `npm run android-standalone` + - For hybrid app `npm run android` + +* If the issue persists, verify that workflow in the GitHub repository have completed successfully: + - [Android builds](https://github.com/Expensify/App/actions/workflows/remote-build-android.yml) + If the workflow is still running, open it and verify it matches your fingerprint. Once complete, Rock should download the remote build. If not, check whether the last main commit hash merged into your branch has the same fingerprint as yours. + + If the fingerprints do not match, run: + - `npx rock fingerprint -p android --verbose` + Compare the results with the GitHub Actions output to see which files have different fingerprints. + +* In the event of workflow failures, it is recommended to have the option to manually build the application. The following steps will cover the manual build process. + +## Running the mobile application using manual builds ### Android-Specific Prerequisites @@ -121,7 +183,7 @@ project.ext.react = [ ``` ### Recording Traces -1. Install the necessary packages: `npm i && npm run pod-install` +1. Install the necessary packages: `npm i` 2. Run your Android app in production mode 3. Navigate to the feature you wish to profile. 4. Initiate the profiling session by tapping with four fingers to open the menu and selecting **`Use Profiling`**. diff --git a/contributingGuides/SETUP_IOS.md b/contributingGuides/SETUP_IOS.md index ddd5aa406354..7af7edc9fc51 100644 --- a/contributingGuides/SETUP_IOS.md +++ b/contributingGuides/SETUP_IOS.md @@ -1,6 +1,68 @@ # iOS Setup Instructions -## Prerequisites +## Running the mobile application using Rock 🪨 + +This project uses [Rock](https://rockjs.dev/) to manage native builds. Rather than compiling native code locally when running commands like `npm run ios`, Rock first attempts to download remote builds (artifacts prebuilt on CI) from a server. If a matching remote build isn’t available, it automatically falls back to building locally. + +By storing complete native build artifacts remotely, Rock reduces the need for local compilation and simplifies setup through automated downloads. + +**Note:** Any changes to files involved in generating a fingerprint (e.g., `package.json`) will trigger a local build. + +The following steps describe how to configure the project to fully utilize Rock. + +### Generating GitHub Personal Access Token + +To take advantage of remote builds, setup your GitHub Personal Access Token (PAT) in your `.env` file: + +1. Create a GitHub Personal Access Token: + - Go to [GitHub Settings > Developer Settings > Personal Access Tokens](https://github.com/settings/tokens) + - Click "Generate new token (classic)" + - Select the following scope: + - `repo` + - Copy the generated token + +2. Add `GITHUB_TOKEN` to `.env` file with your generated token + +### Running the mobile application 📱 +* To install project dependencies run: `npm install` +* To start metro server run: `npm run start` +**Note:** For now this is a required step — metro needs to be called manually in a separate terminal. +* To run application on a **Development Simulator**: + - For standalone `npm run ios-standalone` + - For hybrid app `npm run ios` + +After completing these steps, you should be able to start both mobile platform apps using the remote build. + +### Troubleshooting +If you haven't done any intentional edits outside of `src/` (like adding new dependencies) but your app is still running into a full build, remember that it's way easier to debug and address a remote cache miss rather than any compilation error. + +* Try re-installing dependencies: + - `npm run i-standalone` for the standalone app + - `npm install` for the hybrid app + +* Try running: + - For standalone `npm run ios-standalone` + - For hybrid app `npm run ios` + +* If you’re still encountering errors, you can try running: + - `git clean -fdx ios/` when running standalone app + - `git clean -fdx ./Mobile-Expensify` when running hybrid app + +* Then try running again: + - For standalone `npm run ios-standalone` + - For hybrid app `npm run ios` + +* If the issue persists, verify that both workflows in the GitHub repository have completed successfully: + - [iOS builds](https://github.com/Expensify/App/actions/workflows/remote-build-ios.yml) + If the workflows are still running, open them and verify they match your fingerprint. Once complete, Rock should download the remote build. If not, check whether the last main commit hash merged into your branch has the same fingerprint as yours. + + If the fingerprints do not match, run: + - `npx rock fingerprint -p ios --verbose` + Compare the results with the GitHub Actions output to see which files have different fingerprints. + +* In the event of workflow failures, it is recommended to have the option to manually build the application. The following steps will cover the manual build process. + +## Running the mobile application using manual builds ### iOS-Specific Prerequisites For an M1 Mac, read this [Stack Overflow post](https://stackoverflow.com/questions/64901180/how-to-run-cocoapods-on-apple-silicon-m1) for installing cocoapods. From ef581a1afd8b11724ae130b5efe23d0eecaecca1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kamil=20Str=C3=B3=C5=BC?= Date: Thu, 9 Oct 2025 08:18:36 +0200 Subject: [PATCH 11/11] docs: wording change --- contributingGuides/SETUP_ANDROID.md | 2 +- contributingGuides/SETUP_IOS.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/contributingGuides/SETUP_ANDROID.md b/contributingGuides/SETUP_ANDROID.md index a6e2a7ef04d0..3341efd6a4d8 100644 --- a/contributingGuides/SETUP_ANDROID.md +++ b/contributingGuides/SETUP_ANDROID.md @@ -2,7 +2,7 @@ ## Running the mobile application using Rock 🪨 -This project uses [Rock](https://rockjs.dev/) to manage native builds. Rather than compiling native code locally when running commands like `npm run android`, Rock first attempts to download remote builds (artifacts prebuilt on CI) from a server. If a matching remote build isn’t available, it automatically falls back to building locally. +This project uses [Rock](https://rockjs.dev/) to manage native builds. Rather than compiling native code locally when running commands like `npm run android`, Rock first attempts to download remote builds (artifacts prebuilt on CI) from GitHub. If a matching remote build isn’t available, it automatically falls back to building locally. By storing complete native build artifacts remotely, Rock reduces the need for local compilation and simplifies setup through automated downloads. diff --git a/contributingGuides/SETUP_IOS.md b/contributingGuides/SETUP_IOS.md index 7af7edc9fc51..c4e97d31a30f 100644 --- a/contributingGuides/SETUP_IOS.md +++ b/contributingGuides/SETUP_IOS.md @@ -2,7 +2,7 @@ ## Running the mobile application using Rock 🪨 -This project uses [Rock](https://rockjs.dev/) to manage native builds. Rather than compiling native code locally when running commands like `npm run ios`, Rock first attempts to download remote builds (artifacts prebuilt on CI) from a server. If a matching remote build isn’t available, it automatically falls back to building locally. +This project uses [Rock](https://rockjs.dev/) to manage native builds. Rather than compiling native code locally when running commands like `npm run ios`, Rock first attempts to download remote builds (artifacts prebuilt on CI) from GitHub. If a matching remote build isn’t available, it automatically falls back to building locally. By storing complete native build artifacts remotely, Rock reduces the need for local compilation and simplifies setup through automated downloads.