GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/vscode-react-native

Public

mirrored from https://github.com/microsoft/vscode-react-nativeAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
1.5.2

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

README.md

820lines · modecode

RawDownload
Latest commit unavailable.
1# React Native Tools
2
3[![Build Status](https://dev.azure.com/vscode-webdiag-extensions/VS%20Code%20WebDiag%20extensions/_apis/build/status/%5BUnit%20tests%5D%20vscode-react-native%20%5Bmaster%5D?branchName=master)](https://dev.azure.com/vscode-webdiag-extensions/VS%20Code%20WebDiag%20extensions/_build/latest?definitionId=60&branchName=master)
4
5Stable:
6![Stable version](https://vsmarketplacebadge.apphb.com/version-short/msjsdiag.vscode-react-native.svg)
7![VS Marketplace rating](https://vsmarketplacebadge.apphb.com/rating-star/msjsdiag.vscode-react-native.svg)
8
9Preview:
10![VS Marketplace version](https://vsmarketplacebadge.apphb.com/version-short/msjsdiag.vscode-react-native-preview.svg)
11![VS Marketplace rating](https://vsmarketplacebadge.apphb.com/rating-star/msjsdiag.vscode-react-native-preview.svg)
12
13## React Native Tools Preview
14
15The 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.
16To avoid conflicts, if both extensions are installed - the 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## About the extension
19
20This VS Code extension provides a development environment for React Native projects.
21Using this extension, you can **debug your code and quickly run `react-native` commands** from the command palette.
22
23![React Native features](images/react-features.gif)
24
25<!-- TABLE OF CONTENTS -->
26
27# Table of Contents
28
29- [React Native Tools Preview](#react-native-tools-preview)
30- [About the extension](#about-the-extension)
31- [Getting started](#getting-started)
32- [React Native commands in the Command Palette](#react-native-commands-in-the-command-palette)
33- [Debugging React Native applications](#debugging-react-native-applications)
34 - [Hermes engine](#hermes-engine)
35 - [iOS applications](#ios-applications)
36 - [iOS devices](#ios-devices)
37 - [Custom scheme for iOS apps](#custom-scheme-for-ios-apps)
38 - [iOS direct debugging](#iOS-direct-debugging)
39 - [iOS Hermes debugging](#ios-hermes-debugging)
40 - [Expo applications](#expo-applications)
41 - [Configuring Expo](#configuring-expo)
42 - [Windows applications](#react-native-for-windows)
43 - [macOS applications](#react-native-for-macos)
44 - [macOS Hermes debugging](#macos-hermes-debugging)
45 - [TypeScript and Haul based applications](#typescript-and-haul)
46 - [Debugger configuration properties](#debugger-configuration-properties)
47- [Customization](#customization)
48 - [Logging](#logging)
49 - [Build APK and generate bundle](#build-apk-and-generate-bundle)
50 - [Specifying custom arguments for `react-native run-*` command](#specifying-custom-arguments-for-react-native-run--command)
51 - [Setting up the React Native packager](#setting-up-the-react-native-packager)
52 - [Change project root](#change-project-root)
53 - [Configure an Android LogCat Monitor](#configure-an-android-logcat-monitor)
54- [Network Inspector](#network-inspector)
55- [Developing inside a Docker Container](#developing-inside-a-docker-container)
56- [Contributing](#contributing)
57- [Known Issues](#known-issues)
58
59# Getting started
60
61Before going any further make sure that you:
62
63- [have a working React Native environment](https://reactnative.dev/docs/environment-setup).
64- 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).
65- have your React Native project root folder open in VS Code.
66
67Please 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.
68
69# React Native commands in the Command Palette
70
71In the Command Palette, type `React Native` and choose a command.
72
73![React Native commands](images/command-palette.png)
74
75The **Run Android** command triggers `react-native run-android` and starts your app for Android.
76
77The **Run iOS** command similarly triggers `react-native run-ios` and starts your app in the iOS simulator (e.g. iPhone 6).
78
79The **Packager** commands allow you to start/stop the [**Metro Bundler**](https://github.com/facebook/metro-bundler) (formerly React Packager).
80
81The full list of commands is:
82
83| Name | Description |
84| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
85| Launch Android Emulator | Prompts you to select the name of the available emulator and launch it. If only one emulator is installed in the system, it will be selected automatically |
86| Run Android on Emulator | Run an Android application on Emulator. Launch order: check target platform support, load run arguments, start Packager, run app in all connected emulators |
87| Run Android on Device | Run an Android application on Device. Launch order: check target platform support, load run arguments, start Packager, run app in all connected devices |
88| Run iOS on Simulator | Run an iOS application on Simulator. Launch order: load run arguments, check target platform support, start Packager, run app in only one connected emulator |
89| Run iOS on Device | Run an iOS application on Device. Launch order: load run arguments, check target platform support, start Packager, run app in only one connected device |
90| Run Expo | Run an Exponent application. Launch order: login to exponent, load run arguments, start Packager, run app |
91| Run Windows | Run a RNW application. Launch order: check target platform support, load run arguments, start Packager, run app |
92| Run MacOS | Run a RNmacOS application. Launch order: check target platform support, load run arguments, start Packager, run app |
93| Start Packager | Start Packager in context project workspace folder |
94| Stop Packager | Stop Packager |
95| Restart Packager | Restart Packager |
96| Publish To Expo | Publish to Exponent Host. Launch order: login to exponent, execute `Run Expo` command, then publish app to host |
97| Show Dev Menu | Show development menu for running aplication on iOS or Android device or emulator |
98| ReloadApp | Reload an application |
99| Run Element Inspector | Load development tools for inspect application UI elements |
100| Run React Native LogCat Monitor | 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) |
101| Stop React Native LogCat Monitor | Stops an existing LogCat Monitor and removes its output channel |
102| Run Network Inspector | Run [Network inspector](#network-inspector) |
103| Stop Network Inspector | Stop [Network inspector](#network-inspector) |
104
105# Debugging React Native applications
106
107To start debugging create a new debug configuration for your ReactNative app in your `.vscode/launch.json`. Adding a new configuration can be done by opening your `launch.json` file and clicking on `Add Configuration...` button and choosing a relevant debug configuration. All available debug configurations for ReactNative can be accessed by typing in _ReactNative_ and picking one from the list populated by Intellisense as shown in the image below.
108
109![Add React Native debug configuration](images/add-debug-configuration.gif)
110
111In case you haven't created the `.vscode/launch.json` file yet, you can add a whole default debug configuration set. To do that click the debug icon ![Choose React Native debugger](images/debug-view-icon.png) in the View bar, and then click the configuration (gear) icon ![Configure-gear](images/configure-gear-icon.png), then choose the React Native debug environment.
112
113![Choose React Native debugger](images/choose-debugger.png)
114
115VS Code will generate a `launch.json` in your project with some default configuration settings as shown below. You can safely close this file, choose the appropriate configuration in the Configuration dropdown, and then press F5 (or click _Green Arrow_ ![Configure-gear](images/debug-icon.png) button) to start debugging your app in VS Code.
116
117![React Native launch targets](images/debug-targets.png)
118
119Once app is loaded and running, [open the developer menu](https://reactnative.dev/docs/debugging#accessing-the-in-app-developer-menu) inside your application and enable remote debugging by clicking on `Debug JS Remotely` button.
120
121![React Native enable remote debug](images/enable-remote-debug.png)
122
123The extension allows you to debug multiple devices and configurations, please read the following sections for more information for your particular use case.
124
125## Hermes engine
126
127The 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.
128
129Click [here](https://reactnative.dev/docs/hermes) to learn more about Hermes and how to enable it for your application.
130
131Debugging apps with Hermes enabled is currently experimental. Please, see [this issue](https://github.com/microsoft/vscode-react-native/issues/1073) for current known issues on Hermes support.
132
133### Android Hermes
134
135To debug while using Hermes engine use `Debug Android Hermes - Experimental` launch configuration:
136
137```json
138{
139 "name": "Debug Android Hermes - Experimental",
140 "cwd": "${workspaceFolder}",
141 "type": "reactnativedirect",
142 "request": "launch",
143 "platform": "android"
144}
145```
146
147### iOS Hermes
148
149The extension provides experimental support of debugging iOS Hermes applications. See [iOS Hermes debugging](#ios-hermes-debugging) for more details.
150
151### macOS Hermes
152
153The extension provides experimental support of debugging macOS Hermes applications. See [macOS Hermes debugging](#macos-hermes-debugging) for more details.
154
155### Attach to Hermes application
156
157To attach to a running Hermes application use `Attach to Hermes application - Experimental` launch configuration:
158
159```json
160{
161 "name": "Attach to Hermes application - Experimental",
162 "cwd": "${workspaceFolder}",
163 "type": "reactnativedirect",
164 "request": "attach"
165}
166```
167
168## iOS applications
169
170### iOS devices
171
172Debugging on an iOS device requires following manual steps:
173
174- Install [ios-deploy](https://www.npmjs.com/package/ios-deploy) `npm install -g ios-deploy`.
175- Install a valid iOS development certificate.
176- 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 `device=<iOS_device_name>`, 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" ]`)
177- Choose the **Debug iOS** option from the "Configuration" dropdown and press F5.
178- Shake the device to open the development menu and select "Debug JS Remotely".
179
180### Custom scheme for iOS apps
181
182If you want to use a custom scheme for your application you can either pass it as part of the `runArguments` parameter arguments, or set the `scheme` configuration parameter as shown below:
183
184```js
185"runArguments": ["--scheme", "customScheme", ...]
186// or
187"runArguments": ["--scheme=customScheme", ...]
188// or
189"scheme" : "customScheme"
190```
191
192Please be aware, specifying the scheme value as a part of the `runArguments` parameter arguments will override the `scheme` configuration parameter value, if it set.
193
194### iOS direct debugging
195
196The 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)
197
198For now the extension supports iOS direct debugging only on real iOS devices.
199
200To be able to debug an iOS app directly, you need to install [ios-webkit-debug-proxy](https://github.com/google/ios-webkit-debug-proxy):
201
202- Install [HomeBrew](https://brew.sh) on your Mac.
203- Open a Terminal and run `brew install ideviceinstaller ios-webkit-debug-proxy`
204
205You can use the following debug scenarios to debug iOS apps directly:
206
207- React Native Direct: Debug Direct iOS - Experimental
208
209```json
210 "name": "Debug Direct iOS - Experimental",
211 "cwd": "${workspaceFolder}",
212 "type": "reactnativedirect",
213 "request": "launch",
214 "platform": "ios",
215 "port": 9221,
216 "target": "device"
217```
218
219- React Native Direct: Attach to the React Native iOS - Experimental
220
221```json
222 "name": "Attach to the React Native iOS - Experimental",
223 "cwd": "${workspaceFolder}",
224 "type": "reactnativedirect",
225 "request": "attach",
226 "platform": "ios",
227 "port": 9221
228```
229
230### iOS Hermes debugging
231
232You can enable Hermes engine for an iOS application by editing `ios/Podfile` file the following way:
233
234```diff
235- use_react_native!(:path => config[:reactNativePath])
236+ use_react_native!(:path => config[:reactNativePath], :hermes_enabled => true)
237```
238
239After this change you need to execute `pod install` command in `ios` folder. After that you can use `Debug iOS Hermes - Experimental` launch configuration to debug an iOS Hermes application:
240
241```json
242{
243 "name": "Debug iOS Hermes - Experimental",
244 "cwd": "${workspaceFolder}",
245 "type": "reactnativedirect",
246 "request": "launch",
247 "platform": "ios"
248}
249```
250
251## Expo applications
252
253To debug a project created using Expo or the `create-react-native-app` task, you can use embedded support for Expo.
254
255Prepare your environment by following the [Expo CLI Quickstart instruction](https://reactnative.dev/docs/environment-setup).
256For correct work with Expo this extension **`requires Android SDK`**.
257So also pay attention to the `React Native CLI Quickstart` tab, where you can find the Android SDK installation guide:
258
259- Install the [Expo app](https://getexponent.com/) on the target device or emulator
260- Ensure that the `Android SDK` is installed on your computer (You may install it using the [`React Native CLI Quickstart` guide](https://reactnative.dev/docs/environment-setup))
261- Ensure that the `expo-cli` is installed globally (`npm install -g expo-cli`)
262
263You can verify that everything is working correctly and that the environment is ready for use with the `npx react-native doctor` command.
264
265To start debugging in Expo follow these steps:
266
2671. Open your project in VS Code with this extension installed.
2681. Create a debug configuration (as described in [Debugging React Native applications](#debugging-react-native-applications)), select `Debug in Exponent` in the debug drop-down menu, and start debugging
2691. 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.
2701. If you have not used Exponent on this system before, you will be prompted for an Exponent username and password.
271 Exponent account allows you to use Expo cloud services. More info about how it works is available [here](https://docs.expo.io/versions/latest/workflow/how-expo-works/).
272 If you have not created an Exponent account, then specifying a new username and password will create one.
273 Note that there is no e-mail associated with the account, and no way to recover a forgotten password.
274 If you don't want to create an Exponent account, you can specify `expoHostType` parameter in your debug configuration to make Expo work locally (via LAN or on localhost).
2751. Once the packager starts, the extension will open a separate tab with QR code to scan from the Exponent app. Once you do so, the Exponent app will connect to the packager and begin running your app.
2761. Once the app is loaded and running, [open the developer menu](https://reactnative.dev/docs/debugging#accessing-the-in-app-developer-menu) and enable remote debugging by clicking on `Debug JS Remotely` button.
277
278 ![React Native developer menu](./images/enable-remote-debug.png)
279
280 From here you can run and debug the app as normal.
281
282### Configuring Expo
283
284The 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.
285
286If you are running `Debug in Exponent` configuration or any of pallette 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:
287
288```json
289{
290 "expo": {
291 "slug": "MyApp", // Project slug
292 "name": "MyApp", // Project name
293 "sdkVersion": "31.0.0", // Expo SDK version
294 "entryPoint": ".vscode\\exponentIndex.js" // Entrypoint for the project
295 },
296 "name": "MyApp" // Project name
297}
298```
299
300Full 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).
301
302For 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.
303
304If 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.
305
306**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.
307
308## React Native for Windows
309
310### How to launch and debug a React Native for Windows application
311
312Before launching and debugging a React Native for Windows application, 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).
313
314You can debug UWP React Native for Windows applications by changing the `platform` in your `launch.json` configuration to `windows`:
315
316```json
317{
318 "name": "Debug Windows",
319 "cwd": "${workspaceFolder}",
320 "type": "reactnative",
321 "request": "launch",
322 "platform": "windows"
323}
324```
325
326### How to attach to a running React Native for Windows application
327
3281. Add the `Attach to packager` configuration to `.vscode/launch.json` in your project
329
330 ```json
331 {
332 "name": "Attach to packager",
333 "cwd": "${workspaceFolder}",
334 "type": "reactnative",
335 "request": "attach"
336 }
337 ```
338
3391. (**Optional**) Start Metro packager by means of the `React Native: Start Packager` Command Palette command or run `npx react-native start` command in the terminal in the project root folder
3401. Select the `Attach to packager` configuration and click the `play` button. If Metro packager isn't running yet, the extensnion will start it automatically.
3411. Launch your React Native Windows application. Please make sure that the application is on remote debugging mode.
342
343Then the extension should attach to the running application.
344
345You can find more information on how to setup your application to work with Windows in [React Native for Windows Getting started instruction](https://microsoft.github.io/react-native-windows/docs/getting-started)
346
347## React Native for macOS
348
349You can debug React Native for macOS applications by changing the `platform` in your `launch.json` configuration to `macos`:
350
351```json
352{
353 "name": "Debug macOS",
354 "cwd": "${workspaceFolder}",
355 "type": "reactnative",
356 "request": "launch",
357 "platform": "macos"
358}
359```
360
361To attach to a running macOS application you can use the default `Attach to packager` debugging configuration. Please make sure that the application is on remote debugging mode.
362
363```json
364{
365 "name": "Attach to packager",
366 "cwd": "${workspaceFolder}",
367 "type": "reactnative",
368 "request": "attach"
369}
370```
371
372You can find more information on how to setup your application to work with macOS in [React Native for macOS Getting started instruction](https://microsoft.github.io/react-native-windows/docs/rnm-getting-started)
373
374### macOS Hermes debugging
375
376Please follow [the official guide](https://microsoft.github.io/react-native-windows/docs/hermes#available-on-macos) to enable Hermes engine for a macOS application.
377
378To debug a macOS Hermes application you can use `Debug macOS Hermes - Experimental` debugging scenario:
379
380```json
381{
382 "name": "Debug macOS Hermes - Experimental",
383 "request": "launch",
384 "type": "reactnativedirect",
385 "cwd": "${workspaceFolder}",
386 "platform": "macos"
387}
388```
389
390## TypeScript and Haul
391
392### Sourcemaps
393
394The 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.
395
396The 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.
397
398Below there are some examples of how sourcemaps could be resolved in different scenarios:
399
400```javascript
401// webRoot = /Users/me/project
402"sourceMapPathOverrides": {
403 "webpack:///./~/*": "${webRoot}/node_modules/*", // Example: "webpack:///./~/querystring/index.js" -> "/Users/me/project/node_modules/querystring/index.js"
404 "webpack:///./*": "${webRoot}/*", // Example: "webpack:///./src/app.js" -> "/Users/me/project/src/app.js",
405 "webpack:///*": "*", // Example: "webpack:///project/app.ts" -> "/project/app.ts"
406 "webpack:///src/*": "${webRoot}/*" // Example: "webpack:///src/app.js" -> "/Users/me/project/app.js"
407}
408```
409
410### Haul debugging
411
412The extension provides functional to attach to [Haul packager](https://callstack.github.io/haul/) based applications. You can use the `Attach to packager` scenario to attach to a Haul based app and debug it. For now launch scenarios aren't supported. You can find more info in [the issue](https://github.com/microsoft/vscode-react-native/issues/883).
413
414You can prepare your React Native application to work with `Haul` by following the [`Haul Getting started` guide](https://github.com/callstack/haul#getting-started).
415
416If you use the [legacy version](https://github.com/callstack/haul/tree/legacy) of `Haul` as your React Native bundler instead of the default [Metro](https://facebook.github.io/metro/), it could be required to add `sourceMapPathOverrides` to the `launch.json` file.
417
418For example:
419
420```json
421{
422 // Other configurations
423 "sourceMapPathOverrides": {
424 "webpack:///./~/*": "${workspaceRoot}/node_modules/*",
425 "webpack:///./*": "${workspaceRoot}/*",
426 "webpack:///*": "*"
427 }
428}
429```
430
431## Debugger configuration properties
432
433The following is a list of all the configuration properties the debugger accepts in `launch.json`:
434
435| Name | Description | Type | Defaults |
436| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | --------------------------------------------- |
437| `cwd` | The path to the project root folder | `string` | `${workspaceFolder}` |
438| `sourceMaps` | Whether to use JavaScript source maps to map the generated bundled code back to its original sources | `boolean` | `true` |
439| `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 |
440| `sourceMapRenames` | Whether to use the "names" mapping in sourcemaps. This requires requesting source content, which could slow debugging | `boolean` | `false` |
441| `enableDebug` | Whether to enable debug mode. If set to "false", an application will be launched without debugging | `boolean` | `true` |
442| `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 |
443| `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` |
444| `address` | TCP/IP address of packager to attach to for debugging | `string` | `localhost` |
445| `port` | Port of packager to attach to for debugging | `string` | `8081` |
446| `remoteRoot` | The source root of the remote host | `string` | `null` |
447| `localRoot` | The local source root that corresponds to the 'remoteRoot' | `string` | `${workspaceFolder}` |
448| `skipFiles` | An array of file or folder names, or glob patterns, to skip when debugging | `array` | `[]` |
449| `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/` |
450| `platform` | The platform to target. Possible values: `android`, `ios`, `exponent`, `windows` | `string` | n/a |
451| `target` | Target to run on. Possible values: `simulator`, `device`, `device=<iOS device name>`, [`<Android emulator/device id>`](https://github.com/react-native-community/cli/blob/master/docs/commands.md#--deviceid-string), `<Android emulator name>`, `<iOS simulator name>`, `<iOS simulator id>`. If the value is `simulator` then the quick pick window will be expanded with the names of the available virtual devices, then the target value in `launch.json` will be changed to the name of the selected virtual device. If you have only one virtual device available, it will be selected automatically. | `string` | `simulator` |
452| `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"]` |
453| `runArguments` | Run arguments to be passed to `react-native run-<platform>` command (override all other configuration params) | `array` | n/a |
454| `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` |
455| `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` |
456| `env` | Environment variables passed to the debugger and `react-native run-<platform>` command | `object` | `{}` |
457| `envFile` | Absolute path to a file containing environment variable definitions | `string` | `${workspaceFolder}/.env` |
458| `variant` | A variant to be passed to `react-native run-android`, e.g. use `devDebug` to specify `--variant=devDebug` | `string` | n/a |
459| `scheme` | A scheme name to be passed to `react-native run-ios`, e.g. `devDebug` to specify `--scheme=devDebug` | `string` | n/a |
460| `productName` | iOS bundle display name e.g. `AwesomeProject` value means that the extension will search for `AwesomeProject.app` bundle | `string` | n/a |
461
462# Customization
463
464The extension can be further customized for other React Native scenarios. These are the most common:
465
466## Logging
467
468The extension logging is divided by several output channels:
469
470- React Native - the main extension channel which collects outputs from React Native Packager and shows critical errors in the extension
471- These channels are spawned only when the specific launch scenario is executed:
472 - React Native: Run Android
473 - LogCat monitor(to get LogCat output from Android device, can be filtered by debug configuration settings)
474 - React Native: Run iOS
475 - React Native: Run macOS
476 - React Native: Run exponent
477- 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)
478- Extension debugger verbose logs (these logs are shown up only if the `trace: "verbose"` option is enabled in debug scenarios)
479 - React Native Chrome Proxy - shows what runs in and out to the debugger and application
480 - Debug Console becomes more informative and contains some debugging information from the debug adapter
481 - Global extension errors are controlled by VS Code and printed in VS Code Developer Tools
482
483There are also some global extension technical logs that might be exposed to the output. To see them set the following properties:
484
485```json
486{
487 "react-native-tools": {
488 "logLevel": "Trace"
489 }
490}
491```
492
493`logLevel` can be `None` (no logs), `Error`, `Warning`, `Info`, `Debug`, `Trace` (all logs). Default is `Info`.
494
495## Build APK and generate bundle
496
497You can add VSCode tasks to build an `.apk` file and generate iOS/Android bundles.
498
499The following is an example of a `tasks.json` for `react-native init` projects.
500Place it in the `.vscode` folder in your project to use it:
501
502```json
503{
504 "version": "2.0.0",
505 "presentation": {
506 "reveal": "always",
507 "panel": "new"
508 },
509 "tasks": [
510 {
511 "taskName": "Build APK Debug",
512 "group": "build",
513 "type": "shell",
514 "windows": {
515 "command": "cd android; if($?) {./gradlew assembleDebug}"
516 },
517 "linux": {
518 "command": "cd android && ./gradlew assembleDebug"
519 }
520 },
521 {
522 "taskName": "Build APK Release",
523 "group": "build",
524 "type": "shell",
525 "windows": {
526 "command": "cd android; if($?) {./gradlew assembleRelease}"
527 },
528 "linux": {
529 "command": "cd android && ./gradlew assembleRelease"
530 }
531 },
532 {
533 "taskName": "Generate Android Bundle",
534 "group": "build",
535 "type": "shell",
536 "command": "react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/main.jsbundle"
537 },
538 {
539 "taskName": "Generate iOS Bundle",
540 "group": "build",
541 "type": "shell",
542 "command": "react-native bundle --platform ios --dev false --entry-file index.js --bundle-output ios/main.jsbundle"
543 }
544 ]
545}
546```
547
548To learn more about `tasks` in VSCode read [the official documentation](https://code.visualstudio.com/docs/editor/tasks).
549
550Visit [generating Signed APK](https://reactnative.dev/docs/signed-apk-android.html) to learn more about this subject.
551
552## Specifying custom arguments for `react-native run-*` command
553
554Using custom run arguments for `react-native run-<platform>`:
555**NOTE:** This overrides all other configuration parameters.
556
557```json
558{
559 "react-native.android.runArguments.simulator": [
560 "--appFolder",
561 "/Users/test/AwesomeProject/android/app",
562 "--deviceId",
563 "emulator-5555"
564 ],
565 "react-native.ios.runArguments.device": [
566 "--project-path",
567 "ios",
568 "--device",
569 "Max's iPhone"
570 ]
571}
572```
573
574**NOTE:** You can get the list of installed simulator devices by:
575
576iOS devices (macOS only):
577
578```
579xcrun simctl list --json devices
580```
581
582Android devices:
583
584```
585adb devices
586```
587
588**NOTE:** If you want to run the application on an iOS device, make sure you have `ios-deploy` installed globally.
589
590`npm install -g ios-deploy`
591
592## Setting up the React Native packager
593
594To use a custom port for the `react-native` packager:
595
596```json
597{
598 "react-native": {
599 "packager": {
600 "port": portNumber
601 }
602 }
603}
604```
605
606If you change this port, then for iOS device and simulator scenarios you will have to modify the native code files. [Instructions here](https://blog.binoy.io/running-react-native-on-a-different-port-7deb43887cd4).
607
608If you use Android, you need to change the debug server by:
609
6101. `CTRL+M`(`CMD+M`) in the emulator
6112. Go to `Dev Settings`
6123. Debug server host for device => enter `localhost:<yourPortNumber>`.
6134. Reload application (press `R` twice)
6145. (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).
615
616```js
617// Example of metro.config.js
618module.exports = {
619 server: {
620 port: 9091,
621 },
622};
623```
624
625<details>
626<summary>Port setup instruction</summary>
627
628![image](images/select-dev-menu.png)
629
630![image](images/dev-menu-setup-custom-host.png)
631
632![image](images/custom-host-and-port.png)
633
634</details>
635
636**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).
637
638### Custom environment variables
639
640Extension 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:
641
642```
643
644Variable1_name=Variable1_value
645Variable2_name=Variable2_value
646
647```
648
649Variables that are declared in this `.env` file can override the original environment variables from `process.env` of the Packager process.
650
651It 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.
652
653## Change project root
654
655To 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 here:
656
657```json
658{
659 "react-native-tools": {
660 "projectRoot": "./your/react-native/project"
661 }
662}
663```
664
665## Configure an Android LogCat Monitor
666
667There are two ways to filter your LogCat Monitor output depending on how LogCat Monitor was launched:
668
6691. 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:
670
671```json
672{
673 "name": "Debug Android",
674 "cwd": "${workspaceFolder}",
675 "type": "reactnative",
676 "request": "launch",
677 "platform": "android",
678 "logCatArguments": ["ReactNativeJS:V"]
679}
680```
681
6822. If you want to launch LogCat Monitor from the Command Pallette command `React Native: Run React Native LogCat Monitor` with filtering options set `react-native.android.logCatArguments` settings in your `settings.json`:
683
684```json
685{
686 "react-native.android.logCatArguments": [
687 "*:S",
688 "ReactNative:V",
689 "ReactNativeJS:V"
690 ]
691}
692```
693
694To 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).
695
696## Configure dependencies versions for debugging Expo projects
697
698To 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 setting the `react-native.expo.dependencies.<package name>` parameter in `settings.json`:
699
700```json
701{
702 "react-native.expo.dependencies.xdl": "59.0.42",
703 "react-native.expo.dependencies.metroConfig": "0.1.72"
704}
705```
706
707To 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.
708
709# Network Inspector
710
711The 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.
712
713![image](images/network-inspector.png)
714
715### Network inspector requirements
716
717Before using the Network inspector, please make sure that your system meets the following requirements:
718
719- `OpenSSL` utility is installed and added to PATH. You can install `OpenSSL` the following way:
720 - Windows: `choco install openssl`
721 - macOS: `brew install openssl`
722 - Linux: `sudo apt-get install openssl`
723- (macOS only) [`idb`](https://fbidb.io/docs/installation/) utility is installed. It's required to interact with iOS physical devices
724
725### Network inspector usage
726
727- To run the Network inspector you can use `Run Network Inspector` Command Palette command</br>
728 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.
729- To stop the Network inspector you can use `Stop Network Inspector` Command Palette command
730
731For now the Network inspector doesn't support Expo applications.
732
733# Developing inside a Docker Container
734
735The 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/remote/containers) to setup your environment to use a remote development approach.
736
737You 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).
738
739Here are the steps to run React Native debugging inside a Docker Container on a real Android device:
740
7411. Open Command Palette and run the following command
742 ```
743 Remote-Containers: Add Development Container Configuration Files...
744 ```
745 Then select `Existing Dockerfile` to create `.devcontainer/devcontainer.json` configuration file.
7461. Сreate Dockerfile extending [reactnativecommunity/react-native-android image](https://hub.docker.com/r/reactnativecommunity/react-native-android). For example you can use the following Dockerfile:
747
748 ```
749 FROM reactnativecommunity/react-native-android:latest
750
751 RUN npm install -g expo-cli react-native-cli
752 ```
753
7541. Configure your `devcontainer.json` file as needed. Below is a sample configuration:
755
756 ```json
757 {
758 "name": "React Native Android Container",
759
760 // Sets the run context to one level up instead of the .devcontainer folder.
761 "context": "..",
762
763 // Update the 'dockerFile' property if you aren't using the standard 'Dockerfile' filename.
764 "dockerFile": "Dockerfile",
765
766 // The optional 'runArgs' property can be used to specify additional runtime arguments.
767 "runArgs": [
768 "--privileged", // give all capabilities to a container, in other words, the container can then do almost everything that the host can do
769 "--net",
770 "host", // forwarding all host machine ports
771 "-v",
772 "/dev/bus/usb:/dev/bus/usb" // mount connected USB devices to a container
773 ],
774
775 "settings": {
776 // This will ignore your local shell user setting for Linux since shells like zsh are typically
777 // not in base container images. You can also update this to an specific shell to ensure VS Code
778 // uses the right one for terminals and tasks. For example, /bin/bash (or /bin/ash for Alpine).
779 "terminal.integrated.shell.linux": null
780 },
781
782 // Add the IDs of extensions you want installed when the container is created in the array below.
783 "extensions": ["msjsdiag.vscode-react-native"]
784 }
785 ```
786
7871. Open Command Palette and run the following command `Remote-Containers: Open Folder in Container` to reopen your project in a container
7881. Connect your device via USB and start debugging the same way as on local machine.
789
790Currently 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.
791
792# Contributing
793
794Please see our [contributing guide](CONTRIBUTING.md) for more information.
795
796# Known Issues
797
798Here is the list of common known issues you may experience while using the extension:
799
800| Issue | Description |
801| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
802| 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)) |
803| '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. |
804| Targeting iPhone 6 doesn't work | There was a known issue with React Native ([#5850](https://github.com/facebook/react-native/issues/5850)) but it was fixed. Please upgrade your version of React Native. |
805| 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. |
806| "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)). |
807| 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)). |
808| 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. |
809
810[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.
811
812# Telemetry reporting
813
814VS 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.
815
816If you don’t wish to send usage data to Microsoft, edit `VSCodeTelemetrySettings.json` file at `~/.vscode-react-native` and add `optIn:false`.
817
818# Code of conduct
819
820This 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.