gem-hunter
Language: TypeScript
VSCode extension for React Native - supports debugging and editor integration
Stable:
Preview:
The extension has a nightly version which is released on a daily basis at 9 PM PST on each day that changes occur. 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.
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 to package and install your React Native Tools to get the latest updates.
Building and testing React Native Tools from source requires Node.js 22 or later. This development requirement does not affect the runtime requirements of the installed extension.
This VS Code extension provides a development environment for React Native and Expo projects.
Using this extension, you can debug your code and quickly run react-native or expo commands from the command palette.
react-native run-* commandBefore going any further make sure that you:
PATH or install iOS simulator in MacOSReact Native: Check development environment configuration or React Native: Run expo doctorcommand to make sure that all necessary softwares are installed correctly.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.
In the Command Palette, type React Native and choose a command.
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.
The Run Expo command triggers expo start and starts your expo application.
The Packager commands allow you to start/stop the Metro Bundler (formerly React Packager).
The full list of commands is:
| Name | Command ID | Description |
|---|---|---|
| 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 |
| 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 |
| Launch ExpoWeb | reactNative.launchExpoWeb |
Check if the current project is an Expo project. If so, launch ExpoWeb. |
| 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 |
| 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 |
| 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 |
| 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 |
| Run Expo | reactNative.runExponent |
Run an Exponent application. Launch order: login to exponent, load run arguments, start Packager, run app |
| Run Windows | reactNative.runWindows |
Run a RNW application. Launch order: check target platform support, load run arguments, start Packager, run app |
| Run MacOS | reactNative.runMacOS |
Run a RNmacOS application. Launch order: check target platform support, load run arguments, start Packager, run app |
| Start Packager | reactNative.startPackager |
Start Packager in context project workspace folder |
| Stop Packager | reactNative.stopPackager |
Stop Packager |
| Restart Packager | reactNative.restartPackager |
Restart Packager |
| Clean & Restart Packager (Metro) | reactNative.cleanRestartPackager |
Restart Packager and clear the Packager's cache |
| Expo - Create EAS config file | reactNative.createExpoEASBuildConfigFile |
Create EAS build config file for Expo projects |
| Show Dev Menu | reactNative.showDevMenu |
Show development menu for running application on iOS or Android device or emulator |
| ReloadApp | reactNative.reloadApp |
Reload an application |
| 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. |
| Stop React Native LogCat Monitor | reactNative.stopLogCatMonitor |
Stops an existing LogCat Monitor and removes its output channel |
| Run Network Inspector | reactNative.startNetworkInspector |
Run Network inspector |
| Stop Network Inspector | reactNative.stopNetworkInspector |
Stop Network inspector |
| Check development environment configuration | reactNative.testDevEnvironment |
Checks your development environment for common problems |
| Open the eas project in a web page | reactNative.openEASProjectInWebPage |
Open EAS build in your EAS project portal |
| 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 |
| Expo - Download and install ExpoGo | reactNative.installExpoGoApplication |
Download and install Expo Go application |
| Revert extension input in open package module | reactNative.revertOpenModule |
Quickly revert some codes in Open Module which are changed by react-native-tools |
| Run doctor | reactNative.doctor |
Execute react-native doctor to check basic environment for react-native development |
| Run expo doctor | reactNative.expoDoctor |
Execute expo doctor to check basic environment for Expo development |
| Expo prebuild | reactNative.expoPrebuild |
Create the android and ios directories for running your React code |
| Expo prebuild cleanup | reactNative.expoPrebuildClean |
Clean directories generated by prebuild |
| Reopen QR Code in Expo | reactNative.reopenQRCode |
Reopen expo generated QR code in webview |
| Enable Hermes | reactNative.hermesEnable |
Use hermes as JavaScript engine for RN project |
| Enable & Disable Expo Hermes | reactNative.expoHermesEnable |
Use hermes or jsc as JavaScript engine for expo project |
| Open expo upgrade helper in web page | reactNative.openExpoUpgradeHelper |
Open expo upgrade helper in web browser |
| Install CocoaPods dependencies | reactNative.installPods |
Install CocoaPods dependencies for iOS projects |
| Kill Port | reactNative.killPort |
Kill the process running on a specific port |
| 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 |
| Set React Native New Architecture | reactNative.setNewArch |
Enable or disable the new architecture settings in RN projects |
| Toggle Network View | reactNative.toggleNetworkView |
Enable or disable vscode network view feature for web debugging |
Expo - Create EAS config file runs eas build:configure --platform all for Expo managed projects. If eas.json already exists, the command exits without changing existing config.Publish to Expo Host (reactNative.publishToExpHost) was deprecated and removed. Use Expo EAS workflows (eas build, eas submit) instead.Run EAS Build initializes local EAS build files by creating eas.json and .eas/workflows/create-production-builds.yml when they are missing.Enable Hermes lets you choose platform and enable/disable Hermes:
hermesEnabled property in android/gradle.properties.:hermes_enabled in ios/Podfile and runs pod install.Expo prebuild runs npx expo prebuild from your project root.Kill Port prompts for a port number and runs npx kill-port <port>.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:
{
"version": "2.0.0",
"tasks": [
{
"label": "Run Android on Emulator",
"command": "${command:reactNative.runAndroidSimulator}",
"problemMatcher": []
}
]
}Metro is a JavaScript bundler for React Native and included in React Native package. Metro configuration can be customized in metro.config.js.
To debug react-native application:
launch.json file in .vscode folder.Add Configuration button and choose React Native option.
button) to start debugging your app in VS Code.
Optional: The extension also allows to start debugging without creating the launch.json file in one of the following ways:
Using dynamic debugging configurations
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.
Using Debug button in the Editor Title area menu
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.
The extension allows you to debug multiple devices and configurations, please read the following sections for more information for your particular use case.
React-native set Hermes as default engine. Please see official documentation to get details.
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.
Click here to learn more about Hermes and how to enable it for your application.
To attach to a running Hermes application use Attach to Hermes application launch configuration:
{
"name": "Attach to Hermes application",
"cwd": "${workspaceFolder}",
"type": "reactnativedirect",
"request": "attach"
}To debug while using Hermes engine use Debug Android Hermes launch configuration:
{
"name": "Debug Android Hermes",
"cwd": "${workspaceFolder}",
"type": "reactnativedirect",
"request": "launch",
"platform": "android"
}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:
"runArguments": ["--appIdSuffix", "customAppIdSuffix", ...] // or "runArguments": ["--appIdSuffix=customAppIdSuffix", ...]
To debug your iOS Hermes application, you can use Debug iOS Hermes launch configuration to debug an iOS Hermes application:
{
"name": "Debug iOS Hermes",
"cwd": "${workspaceFolder}",
"type": "reactnativedirect",
"request": "launch",
"platform": "ios"
}Debugging on an iOS device requires following manual steps:
brew install ios-deploy.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" ])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:
"runArguments": ["--scheme", "customScheme", ...] // or "runArguments": ["--scheme=customScheme", ...]
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.
The extension provides experimental support of iOS direct debugging. See more info here: react-native-community/discussions-and-proposals#40, react-native-community/discussions-and-proposals#206
For now the extension supports iOS direct debugging only on real iOS devices.
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.
To be able to debug an iOS app directly, you need to install ios-webkit-debug-proxy:
brew install ideviceinstaller ios-webkit-debug-proxyYou can use the following debug scenarios to debug iOS apps directly:
"name": "Debug Direct iOS - Experimental", "cwd": "${workspaceFolder}", "type": "reactnativedirect", "request": "launch", "platform": "ios", "port": 9221, "target": "device"
"name": "Attach to the React Native iOS - Experimental", "cwd": "${workspaceFolder}", "type": "reactnativedirect", "request": "attach", "platform": "ios", "port": 9221
Extension also support Expo application debugging scenarios.
To create Expo application, please prepare your environment by following the Expo CLI Quickstart instruction.
You can verify if the environment is ready to use by React Native: Run Expo Doctor in command palette.
If you're using Expo Go, follow below steps to start debugging Expo application:
launch.json.{
"name": "Debug Exponent Hermes",
"request": "launch",
"type": "reactnativedirect",
"cwd": "${workspaceFolder}",
"platform": "exponent",
"expoHostType": "local"
}Expo Development Library(xdl) when this feature is used for the first time.
If you want to debug Expo app using expo-dev-client, follow below steps to start debugging Expo application:
npx expo install expo-dev-client.eas build --profile development --platform all, replace --platform all to android or iOS to build specific platform application(need development account for iOS platform).npx expo start --dev-client to start Metro and load application in device or simulator.Attach to application command launch.json, and start debugging.{
"name": "Attach to Hermes application",
"request": "attach",
"type": "reactnativedirect",
"cwd": "${workspaceFolder}"
}Expo support open application in browser, the expo web application is generated by 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:
react-dom, react-native-web and @expo/webpack-config (this package is deprecated from Expo 49) by npx expo install command.launch.json and start debugging.{
"name": "Debug Expo Web",
"request": "launch",
"type": "reactnativedirect",
"cwd": "${workspaceFolder}",
"platform": "expoweb",
"browserTarget": "chrome",
"url": "http://localhost:8081"
}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.)
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:
{
"expo": {
"slug": "MyApp", // Project slug
"name": "MyApp", // Project name
"sdkVersion": "31.0.0", // Expo SDK version
"entryPoint": ".vscode\\exponentIndex.js" // Entrypoint for the project
},
"name": "MyApp" // Project name
}Full list of configuration parameters for expo section in app.json may be found on official Expo documentation page.
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.
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.
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.
Expo using Hermes as default engine, you can switch engine on a specific platform using below configure.
{
"expo": {
"jsEngine": "hermes",
"ios": {
"jsEngine": "jsc"
}
}
}Note: You maybe need to create developer account to run eas build. Any other issue or limitation, please see expo hermes documentation.
The Run EAS Build command (reactNative.runEasBuild) helps you quickly set up Expo Application Services (EAS) Build configuration in your Expo project.
When you run this command from the Command Palette (Ctrl+Shift+P or Cmd+Shift+P), it will:
eas.json file (if it doesn't exist) with an empty configuration {}.eas/workflows/ directory structurecreate-production-builds.yml workflow file with the following content:name: Create Production Builds jobs: build_android: type: build # This job type creates a production build for Android params: platform: android build_ios: type: build # This job type creates a production build for iOS params: platform: ios
Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS) to open the Command PaletteNote: 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.
After running this command, you should:
Configure eas.json: Add your build profiles (e.g., development, preview, production). See EAS Build Configuration for details.
Set up credentials: Configure your iOS and Android signing credentials. Use eas credentials command or configure them in your EAS project.
Run your first build:
# For Android npx eas build --platform android # For iOS npx eas build --platform ios # For both platforms npx eas build --platform all
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.
Monitor builds: Use React Native: Open the eas project in a web page command to view your build status in the EAS dashboard.
For more information about EAS Build, visit the official Expo documentation.
Please make sure that your development environment is configured properly in accordance with the official system requirements.
And follow the official guide to enable Hermes engine for a Windows application.
To debug React Native for Windows applications, you can use below configure in launch.json:
{
"name": "Debug Windows Hermes",
"cwd": "${workspaceFolder}",
"type": "reactnativedirect",
"request": "launch",
"platform": "windows"
}Also you can attach running application using Attach to Hermes application configuration to .vscode/launch.json in your project.
Please make sure that your development environment is configured properly in accordance with the official system requirements.
And follow the official guide to enable Hermes engine for a macOS application.
To debug a macOS Hermes application you can use Debug macOS Hermes debugging scenario:
{
"name": "Debug macOS Hermes",
"request": "launch",
"type": "reactnativedirect",
"cwd": "${workspaceFolder}",
"platform": "macos"
}Also you can attach running application using Attach to Hermes application configuration to .vscode/launch.json in your project.
If you're using monorepo like:
monorepo/
├── apps/
│ ├── app1/
│ │ └── src/
│ └── app2/
│ └── src/
├── packages/
│ ├── ui/
│ │ └── src/
│ └── common/
│ └── src/
│ └── utils.ts
└── package.json
When you import utils.ts in your project. Using
import { commonFunction } from "../../packages/common/src/utils";
Will get error when start Metro:
error: bundling failed: Error: Unable to resolve module `../../packages/common/src/utils` from `src/App.js`
To debug your code in monorepo, please follow below steps:
metro.config.js, add extra module and watch folder.const extraNodeModules = { common: path.resolve(__dirname + "/../packages/common/src"), }; const watchFolders = [path.resolve(__dirname + "/../packages/common/src")]; const config = { resolver: { extraNodeModules, }, watchFolders, };
import { functionInUtils } from "common/utils";
or
import { functionInUtils } from "../../packages/common/src/utils";
launch.json. Example:/* Get source map url from vscode debug diagnostics tab */ "sourceMapPathOverrides": { "/[metro-watchFolders]/1/*": "/Monorepo-Project-Full-Path/*", }
The following is a list of all the configuration properties the debugger accepts in launch.json:
| Name | Description | Type | Defaults |
|---|---|---|---|
cwd |
The path to the project root folder | string |
${workspaceFolder} |
sourceMaps |
Whether to use JavaScript source maps to map the generated bundled code back to its original sources | boolean |
true |
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 for details | object |
n/a |
sourceMapRenames |
Whether to use the "names" mapping in sourcemaps. This requires requesting source content, which could slow debugging | boolean |
false |
enableDebug |
Whether to enable debug mode. If set to "false", an application will be launched without debugging | boolean |
true |
webkitRangeMin, webkitRangeMax |
Combines to specify the port range that you want the ios-webkit-debug-proxy to use to find the specific device described in the Direct iOS debug configuration | 9223, 9322 | |
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 |
address |
TCP/IP address of packager to attach to for debugging | string |
localhost |
port |
Port of packager to attach to for debugging | string |
8081 |
remoteRoot |
The source root of the remote host | string |
null |
localRoot |
The local source root that corresponds to the 'remoteRoot' | string |
${workspaceFolder} |
skipFiles |
An array of file or folder names, or glob patterns, to skip when debugging | array |
[] |
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/ |
platform |
The platform to target. Possible values: android, ios, exponent, windows |
string |
n/a |
target |
Target to run on. Possible values: simulator, device, <iOS target name/udid>, <Android target id>, <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 |
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"] |
runArguments |
Run arguments to be passed to react-native run-<platform> command (override all other configuration params) |
array |
n/a |
launchActivity |
The Android activity to be launched for debugging, e.g. it specifies --main-activity parameter in react-native run arguments |
string |
MainActivity |
expoHostType |
The connection type to be used on Expo debugging to communicate with a device or an emulator. Possible values:
|
string |
lan |
env |
Environment variables passed to the debugger and react-native run-<platform> command |
object |
{} |
envFile |
Absolute path to a file containing environment variable definitions | string |
${workspaceFolder}/.env |
variant |
A variant to be passed to react-native run-android, e.g. use devDebug to specify --variant=devDebug |
string |
n/a |
scheme |
A scheme name to be passed to react-native run-ios, e.g. devDebug to specify --scheme=devDebug |
string |
n/a |
productName |
iOS bundle display name e.g. AwesomeProject value means that the extension will search for AwesomeProject.app bundle |
string |
n/a |
jsDebugTrace |
Enable trace collection for depended extension vscode-js-debug |
boolean |
n/a |
Re.Pack: A modern bundler for React Native applications, powered by Rspack and Webpack.
Haul: A command line tool for developing React Native apps. Legacy tools, recommend using Re.Pack.
Both Re.Pack and Haul can use Attach request to attach to a react-native based app and debug it.
Add config in launch.json file as below, make sure adding sourceMapPathOverrides argument to update source map for your application webpack.
For example:
{
"nam
| |
|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
|