microsoft/vscode-react-native
Publicmirrored from https://github.com/microsoft/vscode-react-nativeAvailable
README.md
1196lines · modecode
| 1 | # React Native Tools |
| 2 | |
| 3 | [](https://dev.azure.com/vscode-webdiag-extensions/VS%20Code%20WebDiag%20extensions/_build/latest?definitionId=60&branchName=master) |
| 4 | |
| 5 | Stable: |
| 6 |  |
| 7 |  |
| 8 | |
| 9 | Preview: |
| 10 |  |
| 11 |  |
| 12 | |
| 13 | ## React Native Tools Preview |
| 14 | |
| 15 | The extension has a [nightly version](https://marketplace.visualstudio.com/items?itemName=msjsdiag.vscode-react-native-preview) which is released on a daily basis at 9 PM PST on each day that changes occur. |
| 16 | To avoid conflicts, if both extensions are installed - only stable version will be activated. So to use the preview version it is needed to disable or remove the stable version and reload VS Code. |
| 17 | |
| 18 | ## Package extension locally |
| 19 | |
| 20 | You can not only download React Native Tools in the marketplace, but can also package your extension `.vsix` installation file by yourself locally. Following [this documentation](https://github.com/microsoft/vscode-react-native/blob/master/CONTRIBUTING.md#build-the-project) to package and install your React Native Tools to get the latest updates. |
| 21 | |
| 22 | ## About the extension |
| 23 | |
| 24 | This VS Code extension provides a development environment for React Native and Expo projects. |
| 25 | Using this extension, you can **debug your code and quickly run `react-native` or `expo` commands** from the command palette. |
| 26 | |
| 27 |  |
| 28 | |
| 29 | <!-- TABLE OF CONTENTS --> |
| 30 | |
| 31 | # Table of Contents |
| 32 | |
| 33 | - [React Native Tools Preview](#react-native-tools-preview) |
| 34 | - [Package extension locally](#package-extension-locally) |
| 35 | - [About the extension](#about-the-extension) |
| 36 | - [Getting started](#getting-started) |
| 37 | - [React Native commands in the Command Palette](#react-native-commands-in-the-command-palette) |
| 38 | - [Customize metro configuration](#customize-metro-configuration) |
| 39 | - [Debugging React Native applications](#debugging-react-native-applications) |
| 40 | - [Hermes engine and direct debugging (Recommended)](#hermes-engine-and-direct-debugging-recommended) |
| 41 | - [Attach to Hermes application](#attach-to-hermes-application) |
| 42 | - [Android applications](#android-applications) |
| 43 | - [Android Hermes Debugging](#android-hermes-debugging) |
| 44 | - [Custom build for android apps](#custom-build-for-android-apps) |
| 45 | - [iOS applications](#ios-applications) |
| 46 | - [iOS Hermes debugging](#ios-hermes-debugging) |
| 47 | - [iOS devices](#ios-devices) |
| 48 | - [Custom scheme for iOS apps](#custom-scheme-for-ios-apps) |
| 49 | - [iOS direct debugging](#iOS-direct-debugging) |
| 50 | - [Expo applications](#expo-applications) |
| 51 | - [Debug on Expo Go](#debug-on-expo-go) |
| 52 | - [Debug on expo-dev-client](#debug-on-expo-dev-client) |
| 53 | - [Debug on Expo Web](#debug-on-expo-web) |
| 54 | - [Configuring Expo](#configuring-expo) |
| 55 | - [Expo Hermes](#expo-hermes) |
| 56 | - [EAS Build initialization](#eas-build-initialization) |
| 57 | - [Windows applications](#react-native-for-windows) |
| 58 | - [Windows Hermes debugging](#windows-hermes-debugging) |
| 59 | - [MacOS applications](#react-native-for-macos) |
| 60 | - [MacOS Hermes debugging](#macos-hermes-debugging) |
| 61 | - [Monorepo: debug out of React Native project directory](#monorepo-debug-out-of-react-native-project-directory) |
| 62 | - [Debugger configuration properties](#debugger-configuration-properties) |
| 63 | - [Re.Pack and Haul debugging](#repack-and-haul-debugging) |
| 64 | - [Remote JavaScript Debugging (Deprecated)](#remote-javascript-debugging-deprecated) |
| 65 | - [Customization](#customization) |
| 66 | - [Sourcemaps](#sourcemaps) |
| 67 | - [Debug in vscode workspace](#debug-in-vscode-workspace) |
| 68 | - [Logging](#logging) |
| 69 | - [Build APK and generate bundle](#build-apk-and-generate-bundle) |
| 70 | - [Specifying custom arguments for `react-native run-*` command](#specifying-custom-arguments-for-react-native-run--command) |
| 71 | - [Setting up the React Native packager](#setting-up-the-react-native-packager) |
| 72 | - [Change project root](#change-project-root) |
| 73 | - [Configure an Android LogCat Monitor](#configure-an-android-logcat-monitor) |
| 74 | - [Configure dependencies versions for debugging Expo projects](#configure-dependencies-versions-for-debugging-expo-projects) |
| 75 | - [Security dependency overrides](#security-dependency-overrides) |
| 76 | - [Configure custom key bindings for extension commands](#configure-custom-key-bindings-for-extension-commands) |
| 77 | - [Configure custom colors for extension output logs](#configure-custom-colors-for-extension-output-logs) |
| 78 | - [Set pnpm as package manager](#set-pnpm-as-package-manager) |
| 79 | - [Network Inspector](#network-inspector) |
| 80 | - [Developing inside a Docker Container](#developing-inside-a-docker-container) |
| 81 | - [Contributing](#contributing) |
| 82 | - [Known Issues](#known-issues) |
| 83 | |
| 84 | # Getting started |
| 85 | |
| 86 | Before going any further make sure that you: |
| 87 | |
| 88 | - [have a working React Native environment](https://reactnative.dev/docs/environment-setup). |
| 89 | - have the Android emulator available in your `PATH` or install iOS simulator in MacOS |
| 90 | - are using [VS Code](https://code.visualstudio.com) and have [installed this extension from the Marketplace](https://marketplace.visualstudio.com/items?itemName=msjsdiag.vscode-react-native). |
| 91 | - have your React Native project root folder open in VS Code. |
| 92 | - have executed `React Native: Check development environment configuration` or `React Native: Run expo doctor`command to make sure that all necessary softwares are installed correctly. |
| 93 | |
| 94 | Please notice that the extension uses `.vscode/.react` directory at the project root to store intermediate files required for debugging. Although these files usually get removed after debug session ends, you may want to add this directory to your project's `.gitignore` file. |
| 95 | |
| 96 | # React Native commands in the Command Palette |
| 97 | |
| 98 | In the Command Palette, type `React Native` and choose a command. |
| 99 | |
| 100 |  |
| 101 | |
| 102 | The **Run Android** or **Run iOS** command triggers `react-native run-android` or `react-native run-ios` to starts your app for Android emulator or iOS simulator. |
| 103 | |
| 104 | The **Run Expo** command triggers `expo start` and starts your expo application. |
| 105 | |
| 106 | The **Packager** commands allow you to start/stop the [**Metro Bundler**](https://github.com/facebook/metro-bundler) (formerly React Packager). |
| 107 | |
| 108 | The full list of commands is: |
| 109 | |
| 110 | | Name | Command ID | Description | |
| 111 | | -------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 112 | | Launch Android Emulator | `reactNative.launchAndroidSimulator` | Prompts you to select the name of the available Android emulator and launch it. If only one emulator is installed in the system, it will be selected automatically | |
| 113 | | Launch iOS Simulator | `reactNative.launchIOSSimulator` | Prompts you to select the available system version of the iOS simulator, then select the simulator name for the selected system and launch it. If only one simulator is installed in the system, it will be selected automatically | |
| 114 | | Launch ExpoWeb | `reactNative.launchExpoWeb` | Check if the current project is an Expo project. If so, launch ExpoWeb. | |
| 115 | | Run Android on Emulator | `reactNative.runAndroidSimulator` | Run an Android application on Emulator. Launch order: check target platform support, load run arguments, start Packager, run app on the selected emulator. Make sure the `emulator` utility is added to `PATH` | |
| 116 | | Run Android on Device | `reactNative.runAndroidDevice` | Run an Android application on Device. Launch order: check target platform support, load run arguments, start Packager, run app in all connected devices | |
| 117 | | Run iOS on Simulator | `reactNative.runIosSimulator` | Run an iOS application on Simulator. Launch order: load run arguments, check target platform support, start Packager, run app in only one connected emulator | |
| 118 | | Run iOS on Device | `reactNative.runIosDevice` | Run an iOS application on Device. Launch order: load run arguments, check target platform support, start Packager, run app in only one connected device | |
| 119 | | Run Expo | `reactNative.runExponent` | Run an Exponent application. Launch order: login to exponent, load run arguments, start Packager, run app | |
| 120 | | Run Windows | `reactNative.runWindows` | Run a RNW application. Launch order: check target platform support, load run arguments, start Packager, run app | |
| 121 | | Run MacOS | `reactNative.runMacOS` | Run a RNmacOS application. Launch order: check target platform support, load run arguments, start Packager, run app | |
| 122 | | Start Packager | `reactNative.startPackager` | Start Packager in context project workspace folder | |
| 123 | | Stop Packager | `reactNative.stopPackager` | Stop Packager | |
| 124 | | Restart Packager | `reactNative.restartPackager` | Restart Packager | |
| 125 | | Clean & Restart Packager (Metro) | `reactNative.cleanRestartPackager` | Restart Packager and clear the Packager's cache | |
| 126 | | Publish To Expo | `reactNative.publishToExpHost` | Publish to Exponent Host. Launch order: login to exponent, execute `Run Expo` command, then publish app to host | |
| 127 | | Expo - Create EAS config file | `reactNative.createExpoEASBuildConfigFile` | Create EAS build config file for Expo projects | |
| 128 | | Show Dev Menu | `reactNative.showDevMenu` | Show development menu for running application on iOS or Android device or emulator | |
| 129 | | ReloadApp | `reactNative.reloadApp` | Reload an application | |
| 130 | |
| 131 | | Run React Native LogCat Monitor | `reactNative.startLogCatMonitor` | Creates a LogCat Monitor for the chosen online Android device to see the device LogCat logs. Default filtering arguments: ["*:S", "ReactNative:V", "ReactNativeJS:V"]. [How to configure filtering.](#configure-an-Android-LogCat-Monitor) | |
| 132 | | Stop React Native LogCat Monitor | `reactNative.stopLogCatMonitor` | Stops an existing LogCat Monitor and removes its output channel | |
| 133 | | Run Network Inspector | `reactNative.startNetworkInspector` | Run [Network inspector](#network-inspector) | |
| 134 | | Stop Network Inspector | `reactNative.stopNetworkInspector` | Stop [Network inspector](#network-inspector) | |
| 135 | | Check development environment configuration | `reactNative.testDevEnvironment` | Checks your development environment for common problems | |
| 136 | | Open the eas project in a web page | `reactNative.openEASProjectInWebPage` | Open EAS build in your EAS project portal | |
| 137 | | Open react native upgrade helper in web page | `reactNative.openRNUpgradeHelper` | Open an official project upgrade tools in browser, support RN, RN for Windows, RN for MacOS | |
| 138 | | Expo - Download and install ExpoGo | `reactNative.installExpoGoApplication` | Download and install Expo Go application | |
| 139 | | Revert extension input in open package module | `reactNative.revertOpenModule` | Quickly revert some codes in Open Module which are changed by react-native-tools | |
| 140 | | Run doctor | `reactNative.doctor` | Execute react-native doctor to check basic environment for react-native development | |
| 141 | | Run expo doctor | `reactNative.expoDoctor` | Execute expo doctor to check basic environment for Expo development | |
| 142 | | Expo prebuild | `reactNative.expoPrebuild` | Create the android and ios directories for running your React code | |
| 143 | | Expo prebuild cleanup | `reactNative.expoPrebuildClean` | Clean directories generated by prebuild | |
| 144 | | Reopen QR Code in Expo | `reactNative.reopenQRCode` | Reopen expo generated QR code in webview | |
| 145 | | Enable Hermes | `reactNative.hermesEnable` | Use hermes as JavaScript engine for RN project | |
| 146 | | Enable & Disable Expo Hermes | `reactNative.expoHermesEnable` | Use hermes or jsc as JavaScript engine for expo project | |
| 147 | | Open expo upgrade helper in web page | `reactNative.openExpoUpgradeHelper` | Open expo upgrade helper in web browser | |
| 148 | | Install CocoaPods dependencies | `reactNative.installPods` | Install CocoaPods dependencies for iOS projects | |
| 149 | | Kill Port | `reactNative.killPort` | Kill the process running on a specific port | |
| 150 | | Run EAS Build | `reactNative.runEasBuild` | Initialize EAS Build configuration by creating `eas.json` and `.eas/workflows/create-production-builds.yml` files if they don't exist | |
| 151 | | Set React Native New Architecture | `reactNative.setNewArch` | Enable or disable the new architecture settings in RN projects | |
| 152 | | Toggle Network View | `reactNative.toggleNetworkView` | Enable or disable vscode network view feature for web debugging | |
| 153 | |
| 154 | ## Using commands in VS Code tasks |
| 155 | |
| 156 | To run React Native Tools commands via VS Code tasks, you can create a `.vscode/tasks.json` file in your project and add tasks configurations the following way: |
| 157 | |
| 158 | ```json |
| 159 | { |
| 160 | "version": "2.0.0", |
| 161 | "tasks": [ |
| 162 | { |
| 163 | "label": "Run Android on Emulator", |
| 164 | "command": "${command:reactNative.runAndroidSimulator}", |
| 165 | "problemMatcher": [] |
| 166 | } |
| 167 | ] |
| 168 | } |
| 169 | ``` |
| 170 | |
| 171 | # Customize metro configuration |
| 172 | |
| 173 | Metro is a JavaScript bundler for React Native and included in React Native package. Metro configuration can be customized in `metro.config.js`. |
| 174 | |
| 175 | # Debugging React Native applications |
| 176 | |
| 177 | To debug react-native application: |
| 178 | |
| 179 | 1. Create `launch.json` file in `.vscode` folder. |
| 180 | 2. Click on `Add Configuration` button and choose `React Native` option. |
| 181 | 3. Select any scenario needed in dropdown list. |
| 182 | |
| 183 |  |
| 184 | |
| 185 | 4. Choose the appropriate configuration in the Configuration dropdown, and then press F5 (or click _Green Arrow_  button) to start debugging your app in VS Code. |
| 186 | |
| 187 |  |
| 188 | |
| 189 | Optional: The extension also allows to start debugging without creating the `launch.json` file in one of the following ways: |
| 190 | |
| 191 | - Using dynamic debugging configurations |
| 192 | |
| 193 | To use dynamic debugging configurations you can click on the `Show all automatic debug configurations` string in the `Run and Debug` panel, then select `React Native` in the list of extensions and choose the appropriate configuration in the Configuration list to start debugging. |
| 194 | |
| 195 |  |
| 196 | |
| 197 | - Using `Debug` button in the Editor Title area menu |
| 198 | |
| 199 | To start debugging you can click the Debug button in the Editor Title area in the upper right corner. You can also select the appropriate debugging scenario by clicking the dropdown button beside the Debug button and choosing the scenario. |
| 200 | |
| 201 |  |
| 202 | |
| 203 | The extension allows you to debug multiple devices and configurations, please read the following sections for more information for your particular use case. |
| 204 | |
| 205 | ## Hermes engine and direct debugging (Recommended) |
| 206 | |
| 207 | React-native set Hermes as default engine. Please see [official documentation](https://reactnative.dev/blog/2022/07/08/hermes-as-the-default) to get details. |
| 208 | |
| 209 | The Hermes engine is an open source JavaScript engine created by Facebook to optimize building and running React Native applications. It improves app performance and decreases app size. |
| 210 | |
| 211 | Click [here](https://reactnative.dev/docs/hermes) to learn more about Hermes and how to enable it for your application. |
| 212 | |
| 213 | ## Attach to Hermes application |
| 214 | |
| 215 | To attach to a running Hermes application use `Attach to Hermes application` launch configuration: |
| 216 | |
| 217 | ```json |
| 218 | { |
| 219 | "name": "Attach to Hermes application", |
| 220 | "cwd": "${workspaceFolder}", |
| 221 | "type": "reactnativedirect", |
| 222 | "request": "attach" |
| 223 | } |
| 224 | ``` |
| 225 | |
| 226 | ## Android applications |
| 227 | |
| 228 | ### Android Hermes debugging |
| 229 | |
| 230 | To debug while using Hermes engine use `Debug Android Hermes` launch configuration: |
| 231 | |
| 232 | ```json |
| 233 | { |
| 234 | "name": "Debug Android Hermes", |
| 235 | "cwd": "${workspaceFolder}", |
| 236 | "type": "reactnativedirect", |
| 237 | "request": "launch", |
| 238 | "platform": "android" |
| 239 | } |
| 240 | ``` |
| 241 | |
| 242 | ### Custom build for Android apps |
| 243 | |
| 244 | If you want to use a custom `applicationIdSuffix` for your application to launch specific build, you can either pass it as part of the `runArguments` parameter arguments as shown below: |
| 245 | |
| 246 | ```js |
| 247 | "runArguments": ["--appIdSuffix", "customAppIdSuffix", ...] |
| 248 | // or |
| 249 | "runArguments": ["--appIdSuffix=customAppIdSuffix", ...] |
| 250 | ``` |
| 251 | |
| 252 | ## iOS applications |
| 253 | |
| 254 | ### iOS Hermes debugging |
| 255 | |
| 256 | To debug your iOS Hermes application, you can use `Debug iOS Hermes` launch configuration to debug an iOS Hermes application: |
| 257 | |
| 258 | ```json |
| 259 | { |
| 260 | "name": "Debug iOS Hermes", |
| 261 | "cwd": "${workspaceFolder}", |
| 262 | "type": "reactnativedirect", |
| 263 | "request": "launch", |
| 264 | "platform": "ios" |
| 265 | } |
| 266 | ``` |
| 267 | |
| 268 | ### iOS devices |
| 269 | |
| 270 | Debugging on an iOS device requires following manual steps: |
| 271 | |
| 272 | - Install [ios-deploy](https://github.com/ios-control/ios-deploy) `brew install ios-deploy`. |
| 273 | - Install a valid iOS development certificate. |
| 274 | - In your project's `launch.json` file set `target` to `device`. If you need to specify the exact device to run, you can set `target` to `<iOS device name/udid>`, or you can also use `runArguments` property to specify a particular device to run on in case multiple devices are connected (e.g. `"runArguments": [ "--device", "My iPhone" ]`) |
| 275 | - Choose the **Debug iOS Hermes** option from the "Configuration" dropdown and press F5. |
| 276 | |
| 277 | ### Custom scheme for iOS apps |
| 278 | |
| 279 | If you want to use a custom scheme for your application you can either pass it as part of the `runArguments` parameter arguments as shown below: |
| 280 | |
| 281 | ```js |
| 282 | "runArguments": ["--scheme", "customScheme", ...] |
| 283 | // or |
| 284 | "runArguments": ["--scheme=customScheme", ...] |
| 285 | ``` |
| 286 | |
| 287 | Please be aware, specifying the scheme value as a part of the `runArguments` parameter arguments will override the `scheme` configuration parameter value, if it set. |
| 288 | |
| 289 | ### iOS direct debugging |
| 290 | |
| 291 | The extension provides experimental support of iOS direct debugging. See more info here: [react-native-community/discussions-and-proposals#40](https://github.com/react-native-community/discussions-and-proposals/issues/40), [react-native-community/discussions-and-proposals#206](https://github.com/react-native-community/discussions-and-proposals/issues/206) |
| 292 | |
| 293 | For now the extension supports iOS direct debugging only on real iOS devices. |
| 294 | |
| 295 | Since this scenarios are using some 3rd party tools for the debugging process. Sometimes it may have limitation from upstream. We still recommend using **Hermes direct debugging** as a first choice. |
| 296 | |
| 297 | To be able to debug an iOS app directly, you need to install [ios-webkit-debug-proxy](https://github.com/google/ios-webkit-debug-proxy): |
| 298 | |
| 299 | - Install [HomeBrew](https://brew.sh) on your Mac. |
| 300 | - Open a Terminal and run `brew install ideviceinstaller ios-webkit-debug-proxy` |
| 301 | |
| 302 | You can use the following debug scenarios to debug iOS apps directly: |
| 303 | |
| 304 | - React Native Direct: Debug Direct iOS - Experimental |
| 305 | |
| 306 | ```json |
| 307 | "name": "Debug Direct iOS - Experimental", |
| 308 | "cwd": "${workspaceFolder}", |
| 309 | "type": "reactnativedirect", |
| 310 | "request": "launch", |
| 311 | "platform": "ios", |
| 312 | "port": 9221, |
| 313 | "target": "device" |
| 314 | ``` |
| 315 | |
| 316 | - React Native Direct: Attach to the React Native iOS - Experimental |
| 317 | |
| 318 | ```json |
| 319 | "name": "Attach to the React Native iOS - Experimental", |
| 320 | "cwd": "${workspaceFolder}", |
| 321 | "type": "reactnativedirect", |
| 322 | "request": "attach", |
| 323 | "platform": "ios", |
| 324 | "port": 9221 |
| 325 | ``` |
| 326 | |
| 327 | ## Expo applications |
| 328 | |
| 329 | Extension also support [Expo](https://expo.dev/) application debugging scenarios. |
| 330 | |
| 331 | To create Expo application, please prepare your environment by following the [Expo CLI Quickstart instruction](https://reactnative.dev/docs/environment-setup). |
| 332 | |
| 333 | You can verify if the environment is ready to use by `React Native: Run Expo Doctor` in command palette. |
| 334 | |
| 335 | ### Debug on Expo Go |
| 336 | |
| 337 | If you're using [Expo Go](https://expo.dev/expo-go), follow below steps to start debugging Expo application: |
| 338 | |
| 339 | 1. Open your project in VS Code with this extension installed. |
| 340 | 2. Add below configure in `launch.json`. |
| 341 | |
| 342 | ```json |
| 343 | { |
| 344 | "name": "Debug Exponent Hermes", |
| 345 | "request": "launch", |
| 346 | "type": "reactnativedirect", |
| 347 | "cwd": "${workspaceFolder}", |
| 348 | "platform": "exponent", |
| 349 | "expoHostType": "local" |
| 350 | } |
| 351 | ``` |
| 352 | |
| 353 | 3. Wait while some dependencies are configured - the extension will install [`Expo Development Library(xdl)`](https://www.npmjs.com/package/xdl) when this feature is used for the first time. |
| 354 | 4. Once the packager starts, the extension will open a separate tab with QR code and app link. You can open app in Expo Go and start debugging. |
| 355 |  |
| 356 | |
| 357 | ### Debug on expo-dev-client |
| 358 | |
| 359 | If you want to debug Expo app using [expo-dev-client](https://docs.expo.dev/development/getting-started/), follow below steps to start debugging Expo application: |
| 360 | |
| 361 | 1. Open your project in VS Code with this extension installed. |
| 362 | 2. In project folder, install expo-dev-client for your app using `npx expo install expo-dev-client`. |
| 363 | 3. Create your app in development mode `eas build --profile development --platform all`, replace `--platform all` to `android` or `iOS` to build specific platform application(need development account for `iOS` platform). |
| 364 | 4. After build success, download your build and install application to your device or simulator. |
| 365 | 5. In project, using `npx expo start --dev-client` to start Metro and load application in device or simulator. |
| 366 | 6. Add `Attach to application` command `launch.json`, and start debugging. |
| 367 | |
| 368 | ```json |
| 369 | { |
| 370 | "name": "Attach to Hermes application", |
| 371 | "request": "attach", |
| 372 | "type": "reactnativedirect", |
| 373 | "cwd": "${workspaceFolder}" |
| 374 | } |
| 375 | ``` |
| 376 | |
| 377 | ### Debug on Expo Web |
| 378 | |
| 379 | Expo support open application in browser, the expo web application is generated by [react-native-web](https://necolas.github.io/react-native-web/). It can help user open application without any Android emulator, iOS simulator or device. React-native-tools supports debugging Expo Web application in Chrome and Edge. Follow below steps to start Expo Web debugging: |
| 380 | |
| 381 | 1. Open your project in VS Code with this extension installed. |
| 382 | 2. Check and install related package: `react-dom`, `react-native-web` and `@expo/webpack-config` (this package is deprecated from Expo 49) by `npx expo install` command. |
| 383 | 3. Add Expo Web debugging configure in `launch.json` and start debugging. |
| 384 | |
| 385 | ```json |
| 386 | { |
| 387 | "name": "Debug Expo Web", |
| 388 | "request": "launch", |
| 389 | "type": "reactnativedirect", |
| 390 | "cwd": "${workspaceFolder}", |
| 391 | "platform": "expoweb", |
| 392 | "browserTarget": "chrome", |
| 393 | "url": "http://localhost:8081" |
| 394 | } |
| 395 | ``` |
| 396 | |
| 397 | ### Configuring Expo |
| 398 | |
| 399 | The extension supports running through Exponent not just the applications created with Expo but even pure React Native applications (in that case you need to add `expo` package to `node_modules` in order to make it work with Expo: `npm install expo --save-dev`. In either cases it uses `app.json` configuration file in the root of the project.) |
| 400 | |
| 401 | If you are running `Debug Exponent Hermes` configuration or any of palette commands like `Run in Exponent`, `Publish to Exponent` then this file will be created automatically if absent or updated with the following basic configuration section: |
| 402 | |
| 403 | ```json |
| 404 | { |
| 405 | "expo": { |
| 406 | "slug": "MyApp", // Project slug |
| 407 | "name": "MyApp", // Project name |
| 408 | "sdkVersion": "31.0.0", // Expo SDK version |
| 409 | "entryPoint": ".vscode\\exponentIndex.js" // Entrypoint for the project |
| 410 | }, |
| 411 | "name": "MyApp" // Project name |
| 412 | } |
| 413 | ``` |
| 414 | |
| 415 | Full list of configuration parameters for `expo` section in `app.json` may be found on [official Expo documentation page](https://docs.expo.io/versions/latest/workflow/configuration). |
| 416 | |
| 417 | For running **pure React Native app**, the extension, creates and uses `.vscode/exponentIndex.js` which points to the app entrypoint (`index.js` or `index.android.js` or `index.ios.js`) file. |
| 418 | |
| 419 | If you want to change your app entrypoint (for example, from `index.js` to `index.android.js`), delete `.vscode/exponentIndex.js` and then restart your debugging session. |
| 420 | |
| 421 | **NOTE**: The extension caches the version of the exponent SDK used by your project. This is helpful since we don't want to install the SDK each time you run exponent. If you want the extension to update the SDK version based on your React Native version, just restart VS Code and if it is supported it should work. If it does not please open an issue. |
| 422 | |
| 423 | ### Expo Hermes |
| 424 | |
| 425 | Expo using Hermes as default engine, you can switch engine on a specific platform using below configure. |
| 426 | |
| 427 | ```json |
| 428 | { |
| 429 | "expo": { |
| 430 | "jsEngine": "hermes", |
| 431 | "ios": { |
| 432 | "jsEngine": "jsc" |
| 433 | } |
| 434 | } |
| 435 | } |
| 436 | ``` |
| 437 | |
| 438 | **Note**: You maybe need to create developer account to run `eas build`. Any other issue or limitation, please see [expo hermes documentation](https://docs.expo.dev/guides/using-hermes/). |
| 439 | |
| 440 | ### EAS Build initialization |
| 441 | |
| 442 | The **Run EAS Build** command (`reactNative.runEasBuild`) helps you quickly set up [Expo Application Services (EAS) Build](https://docs.expo.dev/build/introduction/) configuration in your Expo project. |
| 443 | |
| 444 | #### What it does |
| 445 | |
| 446 | When you run this command from the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`), it will: |
| 447 | |
| 448 | 1. Check if your project root directory is accessible |
| 449 | 2. Create an `eas.json` file (if it doesn't exist) with an empty configuration `{}` |
| 450 | 3. Create the `.eas/workflows/` directory structure |
| 451 | 4. Generate a `create-production-builds.yml` workflow file with the following content: |
| 452 | |
| 453 | ```yaml |
| 454 | name: Create Production Builds |
| 455 | jobs: |
| 456 | build_android: |
| 457 | type: build # This job type creates a production build for Android |
| 458 | params: |
| 459 | platform: android |
| 460 | build_ios: |
| 461 | type: build # This job type creates a production build for iOS |
| 462 | params: |
| 463 | platform: ios |
| 464 | ``` |
| 465 | |
| 466 | #### How to use |
| 467 | |
| 468 | 1. Open your Expo project in VS Code |
| 469 | 2. Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS) to open the Command Palette |
| 470 | 3. Type "Run EAS Build" and select **React Native: Run EAS Build** |
| 471 | 4. The command will create the necessary files if they don't exist |
| 472 | |
| 473 | **Note**: The command is idempotent - it will not overwrite existing files. If the files already exist, the command will skip creation and display an appropriate message. |
| 474 | |
| 475 | #### Next steps after initialization |
| 476 | |
| 477 | After running this command, you should: |
| 478 | |
| 479 | 1. **Configure `eas.json`**: Add your build profiles (e.g., `development`, `preview`, `production`). See [EAS Build Configuration](https://docs.expo.dev/build/eas-json/) for details. |
| 480 | |
| 481 | 2. **Set up credentials**: Configure your iOS and Android signing credentials. Use `eas credentials` command or configure them in your EAS project. |
| 482 | |
| 483 | 3. **Run your first build**: |
| 484 | |
| 485 | ```bash |
| 486 | # For Android |
| 487 | npx eas build --platform android |
| 488 | |
| 489 | # For iOS |
| 490 | npx eas build --platform ios |
| 491 | |
| 492 | # For both platforms |
| 493 | npx eas build --platform all |
| 494 | ``` |
| 495 | |
| 496 | 4. **Customize workflows**: Edit `.eas/workflows/create-production-builds.yml` to add more complex build configurations, such as different build profiles, environment variables, or custom scripts. |
| 497 | |
| 498 | 5. **Monitor builds**: Use `React Native: Open the eas project in a web page` command to view your build status in the EAS dashboard. |
| 499 | |
| 500 | #### Troubleshooting |
| 501 | |
| 502 | - **Permission errors**: Ensure VS Code has write permissions to your project directory |
| 503 | - **Files already exist**: The command will skip file creation if they already exist - this is normal behavior |
| 504 | - **Project not found**: Make sure you have opened a React Native/Expo project folder in VS Code |
| 505 | |
| 506 | For more information about EAS Build, visit the [official Expo documentation](https://docs.expo.dev/build/introduction/). |
| 507 | |
| 508 | ## React Native for Windows |
| 509 | |
| 510 | Please make sure that your development environment is configured properly in accordance with [the official system requirements](https://microsoft.github.io/react-native-windows/docs/rnw-dependencies). |
| 511 | |
| 512 | And follow [the official guide](https://microsoft.github.io/react-native-windows/docs/hermes#hermes-on-windows) to enable Hermes engine for a Windows application. |
| 513 | |
| 514 | ### Windows Hermes debugging |
| 515 | |
| 516 | To debug React Native for Windows applications, you can use below configure in `launch.json`: |
| 517 | |
| 518 | ```json |
| 519 | { |
| 520 | "name": "Debug Windows Hermes", |
| 521 | "cwd": "${workspaceFolder}", |
| 522 | "type": "reactnativedirect", |
| 523 | "request": "launch", |
| 524 | "platform": "windows" |
| 525 | } |
| 526 | ``` |
| 527 | |
| 528 | Also you can attach running application using `Attach to Hermes application` configuration to `.vscode/launch.json` in your project. |
| 529 | |
| 530 | ## React Native for MacOS |
| 531 | |
| 532 | Please make sure that your development environment is configured properly in accordance with [the official system requirements](https://microsoft.github.io/react-native-windows/docs/rnm-dependencies). |
| 533 | |
| 534 | And follow [the official guide](https://microsoft.github.io/react-native-windows/docs/hermes#available-on-macos) to enable Hermes engine for a macOS application. |
| 535 | |
| 536 | ### MacOS Hermes debugging |
| 537 | |
| 538 | To debug a macOS Hermes application you can use `Debug macOS Hermes` debugging scenario: |
| 539 | |
| 540 | ```json |
| 541 | { |
| 542 | "name": "Debug macOS Hermes", |
| 543 | "request": "launch", |
| 544 | "type": "reactnativedirect", |
| 545 | "cwd": "${workspaceFolder}", |
| 546 | "platform": "macos" |
| 547 | } |
| 548 | ``` |
| 549 | |
| 550 | Also you can attach running application using `Attach to Hermes application` configuration to `.vscode/launch.json` in your project. |
| 551 | |
| 552 | ## Monorepo: debug out of React Native project directory |
| 553 | |
| 554 | If you're using monorepo like: |
| 555 | |
| 556 | ``` |
| 557 | monorepo/ |
| 558 | ├── apps/ |
| 559 | │ ├── app1/ |
| 560 | │ │ └── src/ |
| 561 | │ └── app2/ |
| 562 | │ └── src/ |
| 563 | ├── packages/ |
| 564 | │ ├── ui/ |
| 565 | │ │ └── src/ |
| 566 | │ └── common/ |
| 567 | │ └── src/ |
| 568 | │ └── utils.ts |
| 569 | └── package.json |
| 570 | ``` |
| 571 | |
| 572 | When you import `utils.ts` in your project. Using |
| 573 | |
| 574 | ```js |
| 575 | import { commonFunction } from "../../packages/common/src/utils"; |
| 576 | ``` |
| 577 | |
| 578 | Will get error when start Metro: |
| 579 | |
| 580 | ``` |
| 581 | error: bundling failed: Error: Unable to resolve module `../../packages/common/src/utils` from `src/App.js` |
| 582 | ``` |
| 583 | |
| 584 | To debug your code in monorepo, please follow below steps: |
| 585 | |
| 586 | 1. In `metro.config.js`, add extra module and watch folder. |
| 587 | |
| 588 | ```js |
| 589 | const extraNodeModules = { |
| 590 | common: path.resolve(__dirname + "/../packages/common/src"), |
| 591 | }; |
| 592 | |
| 593 | const watchFolders = [path.resolve(__dirname + "/../packages/common/src")]; |
| 594 | |
| 595 | const config = { |
| 596 | resolver: { |
| 597 | extraNodeModules, |
| 598 | }, |
| 599 | watchFolders, |
| 600 | }; |
| 601 | ``` |
| 602 | |
| 603 | 2. Import function in application. |
| 604 | |
| 605 | ```js |
| 606 | import { functionInUtils } from "common/utils"; |
| 607 | ``` |
| 608 | |
| 609 | or |
| 610 | |
| 611 | ```js |
| 612 | import { functionInUtils } from "../../packages/common/src/utils"; |
| 613 | ``` |
| 614 | |
| 615 | 3. Set source map override config in `launch.json`. Example: |
| 616 | |
| 617 | ```json |
| 618 | /* Get source map url from vscode debug diagnostics tab */ |
| 619 | "sourceMapPathOverrides": { |
| 620 | "/[metro-watchFolders]/1/*": "/Monorepo-Project-Full-Path/*", |
| 621 | } |
| 622 | ``` |
| 623 | |
| 624 | 4. Launch app and attach debugger |
| 625 | |
| 626 | ## Debugger configuration properties |
| 627 | |
| 628 | The following is a list of all the configuration properties the debugger accepts in `launch.json`: |
| 629 | |
| 630 | | Name | Description | Type | Defaults | |
| 631 | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | --------------------------------------------- | |
| 632 | | `cwd` | The path to the project root folder | `string` | `${workspaceFolder}` | |
| 633 | | `sourceMaps` | Whether to use JavaScript source maps to map the generated bundled code back to its original sources | `boolean` | `true` | |
| 634 | | `sourceMapPathOverrides` | A set of mappings for rewriting the locations of source files from what the source map says, to their locations on disk. See [Sourcemaps](#sourcemaps) for details | `object` | n/a | |
| 635 | | `sourceMapRenames` | Whether to use the "names" mapping in sourcemaps. This requires requesting source content, which could slow debugging | `boolean` | `false` | |
| 636 | | `enableDebug` | Whether to enable debug mode. If set to "false", an application will be launched without debugging | `boolean` | `true` | |
| 637 | | `webkitRangeMin`, `webkitRangeMax` | Combines to specify the port range that you want the [ios-webkit-debug-proxy](https://github.com/google/ios-webkit-debug-proxy) to use to find the specific device described in the Direct iOS debug configuration | 9223, 9322 | |
| 638 | | `trace` | Logging level in debugger process. May be useful for diagnostics. If set to "Trace" all debugger process logs will be available in `Debug Console` output window | `string` | `log` | |
| 639 | | `address` | TCP/IP address of packager to attach to for debugging | `string` | `localhost` | |
| 640 | | `port` | Port of packager to attach to for debugging | `string` | `8081` | |
| 641 | | `remoteRoot` | The source root of the remote host | `string` | `null` | |
| 642 | | `localRoot` | The local source root that corresponds to the 'remoteRoot' | `string` | `${workspaceFolder}` | |
| 643 | | `skipFiles` | An array of file or folder names, or glob patterns, to skip when debugging | `array` | `[]` | |
| 644 | | `debuggerWorkerUrlPath` | Path to the app debugger worker to override. For example, if debugger tries to attach to http://localhost:8081/debugger-ui/debuggerWorker.js and you get 404 error from packager output then you may want to change debuggerWorkerUrlPath to another value suitable for your packager (\"debugger-ui\" will be replaced with the value you provide) | `string` | `debugger-ui/` | |
| 645 | | `platform` | The platform to target. Possible values: `android`, `ios`, `exponent`, `windows` | `string` | n/a | |
| 646 | | `target` | Target to run on. Possible values: `simulator`, `device`, `<iOS target name/udid>`, [`<Android target id>`](https://github.com/react-native-community/cli/blob/master/docs/commands.md#--deviceid-string), `<Android emulator AVD name>`. If the value is `simulator` or `device` then the quick pick window will be expanded with the names of the available virtual or physical targets, then, in case there are more than one available target with specified type, the target value in `launch.json` will be changed to the name or id of the selected target. If you have only one target with specified type available, it will be selected automatically. If you're using Android emulator targets, please, make sure the `emulator` utility is added to `PATH` | `string` | `simulator` | |
| 647 | | `logCatArguments` | Arguments to be used for LogCat (The LogCat output will appear on an Output Channel). It can be an array such as: `[":S", "ReactNative:V", "ReactNativeJS:V"]` | `array` | `["*:S", "ReactNative:V", "ReactNativeJS:V"]` | |
| 648 | | `runArguments` | Run arguments to be passed to `react-native run-<platform>` command (override all other configuration params) | `array` | n/a | |
| 649 | | `launchActivity` | The Android activity to be launched for debugging, e.g. it specifies [`--main-activity`](https://github.com/react-native-community/cli/blob/master/docs/commands.md#--main-activity-string) parameter in `react-native` run arguments | `string` | `MainActivity` | |
| 650 | | `expoHostType` | The connection type to be used on Expo debugging to communicate with a device or an emulator. Possible values: <ul><li>`tunnel` - allows to deploy and debug an application by means of Expo cloud services</li><li>`lan` - allows to deploy and install an application via your LAN</li><li>`local` - allows to debug an application on an emulator or an Android device without network connection</li></ul> | `string` | `lan` | |
| 651 | | `env` | Environment variables passed to the debugger and `react-native run-<platform>` command | `object` | `{}` | |
| 652 | | `envFile` | Absolute path to a file containing environment variable definitions | `string` | `${workspaceFolder}/.env` | |
| 653 | | `variant` | A variant to be passed to `react-native run-android`, e.g. use `devDebug` to specify `--variant=devDebug` | `string` | n/a | |
| 654 | | `scheme` | A scheme name to be passed to `react-native run-ios`, e.g. `devDebug` to specify `--scheme=devDebug` | `string` | n/a | |
| 655 | | `productName` | iOS bundle display name e.g. `AwesomeProject` value means that the extension will search for `AwesomeProject.app` bundle | `string` | n/a | |
| 656 | | `jsDebugTrace` | Enable trace collection for depended extension `vscode-js-debug` | `boolean` | n/a | |
| 657 | |
| 658 | ## Re.Pack and Haul debugging |
| 659 | |
| 660 | [Re.Pack](https://github.com/callstack/repack): A modern bundler for React Native applications, powered by Rspack and Webpack. |
| 661 | |
| 662 | [Haul](https://github.com/callstack/haul): A command line tool for developing React Native apps. Legacy tools, recommend using Re.Pack. |
| 663 | |
| 664 | Both Re.Pack and Haul can use `Attach` request to attach to a react-native based app and debug it. |
| 665 | Add config in `launch.json` file as below, make sure adding `sourceMapPathOverrides` argument to update source map for your application webpack. |
| 666 | |
| 667 | For example: |
| 668 | |
| 669 | ```json |
| 670 | { |
| 671 | "name": "Attach to Hermes application", |
| 672 | "request": "attach", |
| 673 | "type": "reactnativedirect", |
| 674 | "cwd": "${workspaceFolder}", |
| 675 | "sourceMapPathOverrides": { |
| 676 | "webpack:///./~/*": "${workspaceRoot}/node_modules/*", |
| 677 | "webpack:///./*": "${workspaceRoot}/*", |
| 678 | "webpack:///*": "*" |
| 679 | } |
| 680 | } |
| 681 | ``` |
| 682 | |
| 683 | ## Remote JavaScript Debugging (Deprecated) |
| 684 | |
| 685 | Remote JavaScript debugging is deprecated by react-native team from [0.73](https://reactnative.dev/docs/0.75/other-debugging-methods#remote-javascript-debugging-deprecated) and may be removed officially at any time. |
| 686 | |
| 687 | **We strongly recommend to use [Hermes engine and direct debugging](#hermes-engine-and-direct-debugging-recommended) in your application.** |
| 688 | |
| 689 | Below config showed classic debug mode in extension. With the version update of react-native, some features of Remote JavaScript Debugging may become unavailable, we will remove it from extension in the future if it's totally removed officially. |
| 690 | |
| 691 | ```json |
| 692 | { |
| 693 | "name": "Debug Android", |
| 694 | "request": "launch", |
| 695 | "type": "reactnative", |
| 696 | "cwd": "${workspaceFolder}", |
| 697 | "platform": "android" |
| 698 | } |
| 699 | ``` |
| 700 | |
| 701 | # Customization |
| 702 | |
| 703 | The extension can be further customized for other React Native scenarios. These are the most common: |
| 704 | |
| 705 | ## Sourcemaps |
| 706 | |
| 707 | The debugger uses sourcemaps to let you debug with your original sources, but sometimes the sourcemaps aren't generated properly and overrides are needed. In the config we support `sourceMapPathOverrides`, a mapping of source paths from the sourcemap, to the locations of these sources on disk. Useful when the sourcemap isn't accurate or can't be fixed in the build process. |
| 708 | |
| 709 | The left hand side of the mapping is a pattern that can contain a wildcard, and will be tested against the `sourceRoot` + `sources` entry in the source map. If it matches, the source file will be resolved to the path on the right hand side, which should be an absolute path to the source file on disk. |
| 710 | |
| 711 | Below there are some examples of how sourcemaps could be resolved in different scenarios: |
| 712 | |
| 713 | ```json |
| 714 | // webRoot = /Users/me/project |
| 715 | "sourceMapPathOverrides": { |
| 716 | "webpack:///./~/*": "${webRoot}/node_modules/*", // Example: "webpack:///./~/querystring/index.js" -> "/Users/me/project/node_modules/querystring/index.js" |
| 717 | "webpack:///./*": "${webRoot}/*", // Example: "webpack:///./src/app.js" -> "/Users/me/project/src/app.js", |
| 718 | "webpack:///*": "*", // Example: "webpack:///project/app.ts" -> "/project/app.ts" |
| 719 | "webpack:///src/*": "${webRoot}/*" // Example: "webpack:///src/app.js" -> "/Users/me/project/app.js" |
| 720 | } |
| 721 | ``` |
| 722 | |
| 723 | ## Debug in vscode workspace |
| 724 | |
| 725 | Extension supports vscode multiple root workspace for development. If you have several react-native project in workspace, extension will show project selection list when react-native packager is starting. Also you can add settings in workspace to ignore specific project in selection list. |
| 726 | |
| 727 | - Open vscode command palette, select `Preferences: Open Workspace Settings (JSON)` to open workspace settings file. |
| 728 | - Add below settings in the file: |
| 729 | |
| 730 | ```json |
| 731 | "settings": { |
| 732 | "react-native.workspace.exclude": [ |
| 733 | "ProjectFolderName1", |
| 734 | "ProjectFolderName2" |
| 735 | ] |
| 736 | } |
| 737 | ``` |
| 738 | |
| 739 | - Since the folder selection list is handled by vscode rather than extension, we must set exclude folder when extension is not activated. If you add exclude folder after extension activating, you must re-activate you extension or reopen your vscode. |
| 740 | |
| 741 | ## Logging |
| 742 | |
| 743 | The extension logging is divided by several output channels: |
| 744 | |
| 745 | - React Native - the main extension channel which collects outputs from React Native Packager and shows critical errors in the extension |
| 746 | - These channels are spawned only when the specific launch scenario is executed: |
| 747 | - React Native: Run Android |
| 748 | - LogCat monitor(to get LogCat output from Android device, can be filtered by debug configuration settings) |
| 749 | - React Native: Run iOS |
| 750 | - React Native: Run macOS |
| 751 | - React Native: Run Windows |
| 752 | - React Native: Run exponent |
| 753 | - Debug Console which is used to receive application logs and logs generated by the debug adapter (`console.log` and other `std` outputs from the app) |
| 754 | - Extension debugger verbose logs (these logs are shown up only if the `trace: "verbose"` option is enabled in debug scenarios) |
| 755 | - React Native Chrome Proxy - shows what runs in and out to the debugger and application |
| 756 | - Debug Console becomes more informative and contains some debugging information from the debug adapter |
| 757 | - Global extension errors are controlled by VS Code and printed in VS Code Developer Tools |
| 758 | |
| 759 | There are also some global extension technical logs that might be exposed to the output. To see them set the following properties in your VS Code Settings: |
| 760 | |
| 761 | ```json |
| 762 | { |
| 763 | "react-native-tools": { |
| 764 | "logLevel": "Trace" |
| 765 | } |
| 766 | } |
| 767 | ``` |
| 768 | |
| 769 | `logLevel` can be `None` (no logs), `Error`, `Warning`, `Info`, `Debug`, `Trace` (all logs). Default is `Info`. |
| 770 | |
| 771 | ## Build APK and generate bundle |
| 772 | |
| 773 | You can add VSCode tasks to build an `.apk` file and generate iOS/Android bundles. |
| 774 | |
| 775 | The following is an example of a `tasks.json` for `react-native init` projects. |
| 776 | Place it in the `.vscode` folder in your project to use it: |
| 777 | |
| 778 | ```json |
| 779 | { |
| 780 | "version": "2.0.0", |
| 781 | "presentation": { |
| 782 | "reveal": "always", |
| 783 | "panel": "new" |
| 784 | }, |
| 785 | "tasks": [ |
| 786 | { |
| 787 | "label": "Build APK Debug", |
| 788 | "group": "build", |
| 789 | "type": "shell", |
| 790 | "windows": { |
| 791 | "command": "cd android; if($?) {./gradlew assembleDebug}" |
| 792 | }, |
| 793 | "linux": { |
| 794 | "command": "cd android && ./gradlew assembleDebug" |
| 795 | } |
| 796 | }, |
| 797 | { |
| 798 | "label": "Build APK Release", |
| 799 | "group": "build", |
| 800 | "type": "shell", |
| 801 | "windows": { |
| 802 | "command": "cd android; if($?) {./gradlew assembleRelease}" |
| 803 | }, |
| 804 | "linux": { |
| 805 | "command": "cd android && ./gradlew assembleRelease" |
| 806 | } |
| 807 | }, |
| 808 | { |
| 809 | "label": "Generate Android Bundle", |
| 810 | "group": "build", |
| 811 | "type": "shell", |
| 812 | "command": "npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/main.jsbundle" |
| 813 | }, |
| 814 | { |
| 815 | "label": "Generate iOS Bundle", |
| 816 | "group": "build", |
| 817 | "type": "shell", |
| 818 | "command": "npx react-native bundle --platform ios --dev false --entry-file index.js --bundle-output ios/main.jsbundle" |
| 819 | } |
| 820 | ] |
| 821 | } |
| 822 | ``` |
| 823 | |
| 824 | To learn more about `tasks` in VSCode read [the official documentation](https://code.visualstudio.com/docs/editor/tasks). |
| 825 | |
| 826 | Visit [generating Signed APK](https://reactnative.dev/docs/signed-apk-android) to learn more about this subject. |
| 827 | |
| 828 | ## Specifying custom arguments for `react-native run-*` command |
| 829 | |
| 830 | Using custom run arguments for `react-native run-<platform>`: |
| 831 | **NOTE:** This overrides all other configuration parameters. |
| 832 | |
| 833 | ```json |
| 834 | { |
| 835 | "react-native.android.runArguments.simulator": [ |
| 836 | "--appFolder", |
| 837 | "/Users/test/AwesomeProject/android/app", |
| 838 | "--deviceId", |
| 839 | "emulator-5555" |
| 840 | ], |
| 841 | "react-native.ios.runArguments.device": [ |
| 842 | "--project-path", |
| 843 | "ios", |
| 844 | "--device", |
| 845 | "Max's iPhone" |
| 846 | ] |
| 847 | } |
| 848 | ``` |
| 849 | |
| 850 | **NOTE:** You can get the list of installed simulator devices by: |
| 851 | |
| 852 | iOS devices (macOS only): |
| 853 | |
| 854 | ``` |
| 855 | xcrun simctl list --json devices |
| 856 | ``` |
| 857 | |
| 858 | Android devices: |
| 859 | |
| 860 | ``` |
| 861 | adb devices |
| 862 | ``` |
| 863 | |
| 864 | **NOTE:** If you want to run the application on an iOS device, make sure you have `ios-deploy` installed globally. |
| 865 | |
| 866 | `brew install ios-deploy` |
| 867 | |
| 868 | ## Setting up the React Native packager |
| 869 | |
| 870 | To use a custom port for the `react-native` packager: |
| 871 | |
| 872 | ```json |
| 873 | { |
| 874 | "react-native": { |
| 875 | "packager": { |
| 876 | "port": portNumber |
| 877 | } |
| 878 | } |
| 879 | } |
| 880 | ``` |
| 881 | |
| 882 | If you change this port, then for iOS device and simulator scenarios you will have to modify the native code files. [Instructions here](https://childofcode.com/react-native-0-63-running-on-device-by-other-port-solution/). |
| 883 | |
| 884 | If you use Android, you need to change the debug server by: |
| 885 | |
| 886 | 1. `CTRL+M`(`CMD+M`) in the emulator |
| 887 | 2. Go to `Dev Settings` |
| 888 | 3. Debug server host for device => enter `localhost:<yourPortNumber>`. |
| 889 | 4. Reload application (press `R` twice) |
| 890 | 5. (Hermes only) Hermes engine listens port 8081 for debugging by default, to change it you might need to modify your [`metro.config.js` file adding `"port": portNumber` argument in there to the server settings](https://facebook.github.io/metro/docs/configuration/#port). |
| 891 | |
| 892 | ```js |
| 893 | // Example of metro.config.js (<= 0.72.0) |
| 894 | module.exports = { |
| 895 | server: { |
| 896 | port: 9091, |
| 897 | }, |
| 898 | }; |
| 899 | ``` |
| 900 | |
| 901 | OR |
| 902 | |
| 903 | ```js |
| 904 | // Example of metro.config.js (0.72.0) |
| 905 | const config = { |
| 906 | server: { |
| 907 | port: 9091, |
| 908 | }, |
| 909 | }; |
| 910 | ``` |
| 911 | |
| 912 | <details> |
| 913 | <summary>Port setup instruction</summary> |
| 914 | |
| 915 |  |
| 916 | |
| 917 |  |
| 918 | |
| 919 |  |
| 920 | |
| 921 | </details> |
| 922 | |
| 923 | **NOTE:** Some aspects of React Native hard-code the port to the default as specified in [this issue](https://github.com/facebook/react-native/issues/9145). |
| 924 | |
| 925 | ### Custom environment variables |
| 926 | |
| 927 | Extension supports passing custom environment variables to the React Native Packager process context. To add custom variables you can create `.env` file in the root folder of your project and add needed environment variables in the following format: |
| 928 | |
| 929 | ``` |
| 930 | |
| 931 | Variable1_name=Variable1_value |
| 932 | Variable2_name=Variable2_value |
| 933 | |
| 934 | ``` |
| 935 | |
| 936 | Variables that are declared in this `.env` file can override the original environment variables from `process.env` of the Packager process. |
| 937 | |
| 938 | It is possible to transfer environment variables (via `env` and `envFile` arguments in `launch.json`) from the `launch` or `attach` debug scenarios to the Packager. If these variables are defined, then they will be used, otherwise the `.env` file is used. |
| 939 | |
| 940 | ## Change project root |
| 941 | |
| 942 | To specify a subfolder in which the react-native project is located, set `react-native-tools.projectRoot`. You can use either an absolute or relative path in your VS Code Settings: |
| 943 | |
| 944 | ```json |
| 945 | { |
| 946 | "react-native-tools": { |
| 947 | "projectRoot": "./your/react-native/project" |
| 948 | } |
| 949 | } |
| 950 | ``` |
| 951 | |
| 952 | ## Configure an Android LogCat Monitor |
| 953 | |
| 954 | There are two ways to filter your LogCat Monitor output depending on how LogCat Monitor was launched: |
| 955 | |
| 956 | 1. Since LogCat Monitor is launched for all Android launch scenarios by default, you can add `logCatArguments` to your debug scenario in `launch.json` file like in the following example: |
| 957 | |
| 958 | ```json |
| 959 | { |
| 960 | "name": "Debug Android Hermes", |
| 961 | "cwd": "${workspaceFolder}", |
| 962 | "type": "reactnativedirect", |
| 963 | "request": "launch", |
| 964 | "platform": "android", |
| 965 | "logCatArguments": ["ReactNativeJS:V"] |
| 966 | } |
| 967 | ``` |
| 968 | |
| 969 | 2. If you want to launch LogCat Monitor from the Command Palette command `React Native: Run React Native LogCat Monitor` with filtering options set `react-native.android.logCatArguments` settings in your `settings.json`: |
| 970 | |
| 971 | ```json |
| 972 | { |
| 973 | "react-native.android.logCatArguments": [ |
| 974 | "*:S", |
| 975 | "ReactNative:V", |
| 976 | "ReactNativeJS:V" |
| 977 | ] |
| 978 | } |
| 979 | ``` |
| 980 | |
| 981 | To have better understanding on how LogCat filtering works take into account that the extension launches LogCat with flag `-s` and then adds user-provided filters as arguments. Please see the [official instruction on how does LogCat filtering works](https://developer.android.com/studio/command-line/logcat#filteringOutput). |
| 982 | |
| 983 | ## Configure dependencies versions for debugging Expo projects |
| 984 | |
| 985 | To debug Expo applications the extension requires additional dependencies, such as `xdl` and `@expo/metro-config`. These packages are installed automatically on the first start of the Expo debugging scenario. You can configure the dependencies versions by adding the `react-native.expo.dependencies` parameter, which contains packages names and appropriate versions, to the `settings.json` file: |
| 986 | |
| 987 | ```json |
| 988 | { |
| 989 | "react-native.expo.dependencies": { |
| 990 | "xdl": "59.2.0", |
| 991 | "@expo/metro-config": "0.2.0", |
| 992 | "@expo/ngrok": "^4.1.0" |
| 993 | } |
| 994 | } |
| 995 | ``` |
| 996 | |
| 997 | To enable new versions of the dependencies, it's required to restart VS Code editor. After that the extension will download the new versions of the packages on the next Expo debugging starting. |
| 998 | |
| 999 | ## Security dependency overrides |
| 1000 | |
| 1001 | Recent repository updates include a security pin for `serialize-javascript` via npm `overrides`. |
| 1002 | If you maintain a fork or run local dependency audits, align your `package.json` with the following: |
| 1003 | |
| 1004 | ```json |
| 1005 | { |
| 1006 | "overrides": { |
| 1007 | "js-yaml": "4.1.1", |
| 1008 | "serialize-javascript": "7.0.5" |
| 1009 | } |
| 1010 | } |
| 1011 | ``` |
| 1012 | |
| 1013 | After updating `package.json`, run your package manager install command to refresh the lock file. |
| 1014 | |
| 1015 | ## Configure custom key bindings for extension commands |
| 1016 | |
| 1017 | The extension provides context variables for the following features: |
| 1018 | |Context variable|Feature| |
| 1019 | |---|---| |
| 1020 | |`isRNPackagerRunning` - true if the packager is running|Metro packager| |
| 1021 | |`isRNTNetworkInspectorRunning` - true if the Network inspector is running|Network inspector| |
| 1022 | |
| 1023 | Using these context variables you can assign the same keyboard combination for some pair commands for more convenient use. For example, you can configure the same key bindings for `Start Packager` and `Stop Packager` commands using `when` clauses, as shown below: |
| 1024 |  |
| 1025 | |
| 1026 | ## Configure custom colors for extension output logs |
| 1027 | |
| 1028 | The extension provides custom TextMate tokens, with the help of which it is now possible to customize the colors of the logs in output channels: |
| 1029 | |Scope|Description| |
| 1030 | |---|---| |
| 1031 | |`rnt.output.string`|Single and double quoted strings| |
| 1032 | |`rnt.output.url`|Links, email and ip address, filepaths| |
| 1033 | |`rnt.output.timestamp`|Date and time| |
| 1034 | |`rnt.output.numeric`|Constant decimal numbers| |
| 1035 | |`rnt.output.process`|Logs of processes such as npm, bundle, and other build tasks| |
| 1036 | |`rnt.output.error`|Errors, exceptions, fails and stack for them| |
| 1037 | |`rnt.output.warn`|Warning logs| |
| 1038 | |`rnt.output.info`|Info logs| |
| 1039 | |`rnt.output.debug`|Debug logs| |
| 1040 | |`rnt.output.verbose`|Verbose logs| |
| 1041 | |`rnt.output.constant`|Such values as `true`, `false`, `null`, `undefined`, `NaN`| |
| 1042 | |`rnt.output.success`|Logs indicating successful completion of the process, such as `BUILD SUCCESSFUL` and others| |
| 1043 | |
| 1044 | Now you can customize React Native Tools output logs with `editor.tokenColorCustomizations` parameter in `settings.json` this way: |
| 1045 | |
| 1046 | ```json |
| 1047 | "editor.tokenColorCustomizations": { |
| 1048 | "textMateRules": [ |
| 1049 | { |
| 1050 | "settings": { |
| 1051 | "foreground": "#c57ca0", |
| 1052 | "fontStyle": "bold", |
| 1053 | }, |
| 1054 | "scope": "rnt.output.string" |
| 1055 | } |
| 1056 | ] |
| 1057 | } |
| 1058 | ``` |
| 1059 | |
| 1060 | ## Set pnpm as package manager |
| 1061 | |
| 1062 | If you want to use pnpm as your package manager, please set `react-native-tools.setPackageManager` settings in your `settings.json`: |
| 1063 | |
| 1064 | ```json |
| 1065 | { |
| 1066 | "react-native-tools.setPackageManager": "pnpm" |
| 1067 | } |
| 1068 | ``` |
| 1069 | |
| 1070 | # Network Inspector |
| 1071 | |
| 1072 | The extension provides `Network inspector` feature to inspect outgoing network traffic in your apps. You can browse all requests being made and their responses in VS Code DevTools console. |
| 1073 | |
| 1074 |  |
| 1075 | |
| 1076 | ### Network inspector requirements |
| 1077 | |
| 1078 | Before using the Network inspector, please make sure that your system meets the following requirements: |
| 1079 | |
| 1080 | - `OpenSSL` utility is installed and added to PATH. You can install `OpenSSL` the following way: |
| 1081 | - Windows: `choco install openssl` |
| 1082 | - macOS: `brew install openssl` |
| 1083 | - Linux: `sudo apt-get install openssl` |
| 1084 | - (macOS only) [`idb`](https://fbidb.io/docs/installation/) utility is installed. It's required to interact with iOS physical devices |
| 1085 | |
| 1086 | The Network inspector uses functional of the Flipper plugin integrated to React Native apps. Please make sure that it's enabled in your application. You can use [this guide](https://fbflipper.com/docs/getting-started/react-native/) to integrate Flipper into your projects. |
| 1087 | |
| 1088 | ### Network inspector usage |
| 1089 | |
| 1090 | - To run the Network inspector you can use `Run Network Inspector` Command Palette command</br> |
| 1091 | When the Network inspector detects a React Native application and connects to it, VS Code DevTools window will be opened automatically. But you can also open it manually, by opening `Help` menu and clicking `Toggle Developer Tools` option. After that you just need to open `Console` tab in DevTools, where network requests will be printed. |
| 1092 | - To stop the Network inspector you can use `Stop Network Inspector` Command Palette command |
| 1093 | |
| 1094 | For now the Network inspector doesn't support Expo applications. |
| 1095 | |
| 1096 | ### Network inspector logs theme |
| 1097 | |
| 1098 | The extension provides “Dark” and “Light” color themes for Network Inspector logs. You can configure the theme in the extension configuration in your VS Code Settings. |
| 1099 | |
| 1100 | ```json |
| 1101 | { |
| 1102 | "react-native-tools.networkInspector.consoleLogsColorTheme": "Dark" |
| 1103 | } |
| 1104 | ``` |
| 1105 | |
| 1106 | # Developing inside a Docker Container |
| 1107 | |
| 1108 | The extension supports [VS Code Remote Development](https://code.visualstudio.com/docs/remote/remote-overview) features on Linux. Please follow the [VS Code official documentation](https://code.visualstudio.com/docs/devcontainers/containers) to setup your environment and install related extensions([Remote Development](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack) is recommended) to use a remote development approach. |
| 1109 | |
| 1110 | You can use [official React Native Docker image](https://hub.docker.com/r/reactnativecommunity/react-native-android) provided by the [react-native-community](https://github.com/react-native-community/docker-android). |
| 1111 | |
| 1112 | Here are the steps to run React Native debugging inside a Docker Container on a real Android device: |
| 1113 | |
| 1114 | 1. In the local react-native project, add `Dev Container` configure folder and files: |
| 1115 | ``` |
| 1116 | .devcontainer |
| 1117 | -devcontainer.json |
| 1118 | -Dockerfile |
| 1119 | ``` |
| 1120 | 2. Create Dockerfile extending [reactnativecommunity/react-native-android image](https://hub.docker.com/r/reactnativecommunity/react-native-android). For example you can use the following Dockerfile: |
| 1121 | |
| 1122 | ``` |
| 1123 | FROM reactnativecommunity/react-native-android:latest |
| 1124 | |
| 1125 | RUN npm install -g expo-cli react-native-cli |
| 1126 | ``` |
| 1127 | |
| 1128 | 3. Configure your `devcontainer.json` file as needed. Below is a sample configuration: |
| 1129 | |
| 1130 | ```json |
| 1131 | { |
| 1132 | "name": "React Native Android Container", |
| 1133 | |
| 1134 | // Sets the run context to one level up instead of the .devcontainer folder. |
| 1135 | "context": "..", |
| 1136 | |
| 1137 | // Update the 'dockerFile' property if you aren't using the standard 'Dockerfile' filename. |
| 1138 | "dockerFile": "Dockerfile", |
| 1139 | |
| 1140 | // The optional 'runArgs' property can be used to specify additional runtime arguments. |
| 1141 | "runArgs": [ |
| 1142 | "--privileged", // give all capabilities to a container, in other words, the container can then do almost everything that the host can do |
| 1143 | "--net", |
| 1144 | "host", // forwarding all host machine ports |
| 1145 | "-v", |
| 1146 | "/dev/bus/usb:/dev/bus/usb" // mount connected USB devices to a container |
| 1147 | ], |
| 1148 | "customizations": { |
| 1149 | "vscode": { |
| 1150 | "settings": { |
| 1151 | // This will ignore your local shell user setting for Linux since shells like zsh are typically |
| 1152 | // not in base container images. You can also update this to an specific shell to ensure VS Code |
| 1153 | // uses the right one for terminals and tasks. For example, /bin/bash (or /bin/ash for Alpine). |
| 1154 | "terminal.integrated.shell.linux": null |
| 1155 | }, |
| 1156 | // Add the IDs of extensions you want installed when the container is created in the array below. |
| 1157 | "extensions": ["msjsdiag.vscode-react-native"] |
| 1158 | } |
| 1159 | } |
| 1160 | } |
| 1161 | ``` |
| 1162 | |
| 1163 | 4. Open Command Palette and run the following command `Dev Containers: Open Folder in Container` to reopen your project in a container |
| 1164 | 5. Connect your device via USB and start debugging the same way as on local machine. |
| 1165 | |
| 1166 | Currently the above scenario doesn't work on macOS and Windows. Docker Container implementation on these OS uses Virtual Machine tools which may have problems with USB forwarding for mobile devices. |
| 1167 | |
| 1168 | # Contributing |
| 1169 | |
| 1170 | Please see our [contributing guide](CONTRIBUTING.md) for more information. |
| 1171 | |
| 1172 | # Known Issues |
| 1173 | |
| 1174 | Here is the list of common known issues you may experience while using the extension: |
| 1175 | |
| 1176 | | Issue | Description | |
| 1177 | | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 1178 | | Debugger doesn't stop at breakpoints | Breakpoints require sourcemaps to be correctly configured. If you are using TypeScript, then make sure to follow the `Getting started` section for how to ensure sourcemaps are correctly set up. Also, similar issues may occur on React Native version `0.58.*` in some special cases (see [#928](https://github.com/microsoft/vscode-react-native/issues/928), [#907](https://github.com/microsoft/vscode-react-native/issues/907)), bumping dependencies versions of `react` and `react-native` package to the more recent ones should resolve these. If you are on Linux, make sure that the project folder which is opened is not a symbolic link to the real folder, that might cause problems with sourcemaps (see [#1456](https://github.com/microsoft/vscode-react-native/issues/1456)) | |
| 1179 | | 'adb: command not found' | If you receive an error `adb: command not found`, you need to update your system Path to include the location of your _ADB_ executable.The _ADB_ executable file is located in a subdirectory along with your other Android SDK files. | |
| 1180 | | Can't communicate with socket pipe | (Linux only) If you have two workspaces open that only differ in casing, the extension will fail to communicate effectively. | |
| 1181 | | "Add configuration" button doesn't work when trying to add debug configuration to `launch.json` | You have to add some json configuration to `launch.json` manually. Please, see ([#985](https://github.com/microsoft/vscode-react-native/issues/985)). | |
| 1182 | | Error `None of these files exist: * .vscode/exponentIndex` appears when running React Native apps via Expo | On some project configurations (mostly on macOS) there could be problems with running RN app via Expo for the first time. You can resolve this by explicitly adding `module.exports.watchFolders = ['.vscode'];` to your Metro config. This will help Metro bundler to find the custom entry point generated by the extension needed to work with Expo. For details you can see the issue ([#1327](https://github.com/microsoft/vscode-react-native/issues/1327)). | |
| 1183 | | High CPU load notification while starting debugging Expo app | When you start debugging the Expo application you may receive the notification `"The extension 'React Native Tools' took a very long time to complete its last operation and it has prevented other extensions from running"`. The issue occurs because of importing the `xdl` package, which extension uses for debugging Expo applications. The `xdl` package has the large size and some peculiarities of its structure, so it may cause high CPU load. | |
| 1184 | |
| 1185 | [Known-Issues](https://github.com/microsoft/vscode-react-native/issues?q=is%3Aissue+label%3Aknown-issues) provides a complete list of active and resolved issues. |
| 1186 | |
| 1187 | # Telemetry reporting |
| 1188 | |
| 1189 | VS Code React Native extension collects usage data and sends it to Microsoft to help improve our products and services. Read our [privacy statement](https://www.visualstudio.com/en-us/dn948229) to learn more. |
| 1190 | |
| 1191 | If you don’t wish to send usage data to Microsoft: |
| 1192 | create and add `VSCodeTelemetrySettings.json` file at `~/.vscode-react-native` and add `optIn:false`. Or add `react-native-tools.telemetry.optIn: false` in `~/.vscode/settings.json` file. |
| 1193 | |
| 1194 | # Code of conduct |
| 1195 | |
| 1196 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. |
| 1197 | |