JavaScript Debugging
This page details how to debug the JavaScript code in your RNW applications, including which tools are supported in which scenarios. You have two different options: Web Debugging and Direct Debugging.
Unless stated otherwise, each of the debugging scenarios detailed below assume you're loading your JS bundle from the Metro Packager, not loading a prebuilt bundle file.
Web Debugging
Web Debugging (also referred to as Remote JS Debugging) is the original JS debugging solution for RN.
It works by running your app's JS code within the JS engine of an external process, usually a web browser such as Edge (or Chrome). You're then able to debug your app using the development tools of that external process, i.e. the browser's web development tools.
Web Debugging requires the Metro Packager, as Metro proxies the connection between your native Windows app and the remote JS engine.
Web Debugging Tool Support
JavaScript Engine | Edge Developer Tools | Visual Studio Code w/ React Native Tools |
---|---|---|
Chakra (Default) | ✅ | ✅ |
Hermes | ✅ | ✅ |
Important: As your code is run in the remote JS engine, the app's embedded engine is not used. This can cause your released app to behave differently when it is using the embedded engine. See Web vs. Direct Debugging for details.
Step 1: Enable Web Debugging
You have two options to enable Web Debugging: at compile-time in your app's native code or at runtime via the in-app Developer Menu.
UseWebDebugger
in your native code
Option 1: Setting Web Debugging can be enabled by setting UseWebDebugger
property of your app's InstanceSettings
during startup.
Modifying your C# RNW app
- You'll want to edit your
App
's constructor inApp.xaml.cs
with:
InstanceSettings.UseWebDebugger = true;
InstanceSettings.UseDirectDebugger = false;
Modifying your C++ RNW app
- You'll want to edit your
App
's constructor inApp.cpp
with:
InstanceSettings().UseWebDebugger(true);
InstanceSettings().UseDirectDebugger(false);
- Then simply re-build and launch your RNW app as usual.
For a new RNW app created using
react-native-windows-init
,UseWebDebugger
defaults totrue
for Debug builds, andfalse
for Release builds.
Option 2: Using the Developer Menu
Web Debugging can also be enabled at runtime via the in-app Developer Menu.
- With your RNW app running, press
Ctrl+Shift+D
to invoke the Developer Menu - Click Enable Remote JS Debugging
The app then should automatically refresh with Web Debugging enabled.
Step 2: Connect a debugger
The next step is to connect to Metro with your chosen debugger / development tools.
This must happen before the native app attempts to download the JS bundle from Metro. If a debugger is not already attached, Metro will automatically attempt to set up the Edge Developer Tools.
Using the Edge Developer Tools
You can web debug within Edge by using the Edge Developer Tools.
If you use Chrome, the process is similar for using the Chrome Developer Tools.
- Launch your RNW app (with Web Debugging enabled and Metro running)
- In Edge, open the URL http://localhost:8081/debugger-ui/
Metro may have already opened it, look for a React Native Debugger tab.
- Press
Ctrl+Shift+J
on the page to launch the Developer Tools
You should now be able to debug your RNW application. To set breakpoints you'll find your app's JS source files in the Sources tab under debuggerWorker.js
> localhost:8081
> src/ui
.
Using Visual Studio Code with the React Native Tools
You can web debug within VS Code by using the React Native Tools extension.
Important: You will not be able to connect VS Code to Metro if the Edge Developer Tools (or another debugger) is already connected. So double check you don't have any previous React Native Debugger browser tabs open before running these steps.
- Make sure you have VS Code and the React Native Tools extension installed
- Open your project's root folder in VS Code
- Click on the Run and Debug button in the sidebar or press
Ctrl+Shift+D
- Click on the drop-down at the top of the sidebar and select React Native...
If there's no drop-down, click on Show all automatic debug configurations then select React Native... from the drop-down that appears.
Option A: Let VS Code launch everything and start debugging
- Click on the ⚙️ to the right of Debug Windows
- A new configuration should appear in your
launch.json
file. Rename it if you want but it should look like:
{
"name": "Debug Windows",
"cwd": "${workspaceFolder}",
"type": "reactnative",
"request": "launch",
"platform": "windows",
"isDynamic": true
}- Make sure that Metro, your native app, and/or any browser Developer Tools are not already running
- Make sure the new config is selected at the top of the Run and Debug sidebar
- Click on the ▶️ button or press
F5
in VS Code
Watch VS Code's Debug Console output for a successful debugger connection. This can be very slow, but VS Code should automatically launch Metro, establish the debugger connection, then launch your native app to download the bundle.
Option B: Attach VS Code to Metro that's already running
- Click on the ⚙️ to the right of Attach to packager
- A new configuration should appear in your
launch.json
file. Rename it if you want but it should look like:
{
"name": "Attach to packager",
"cwd": "${workspaceFolder}",
"type": "reactnative",
"request": "attach",
"isDynamic": true
}- Make sure that only Metro is already running (i.e.
npx react-native start
) - Make sure the new config is selected at the top of the Run and Debug sidebar
- Click on the ▶️ button or press
F5
in VS Code - Confirm the address of the Metro server (default:
localhost
) - Confirm the port of the Metro server (default:
8081
)
Watch VS Code's Debug Console output for a successful debugger connection.
- Manually launch your native app
Once everything is running, you should be able to debug your RNW application. To set breakpoints, simply do so in your app's JS source files directly in VS Code.
Remember to save
launch.json
so you can reuse this debugging configuration in the future.
Important: If you're having difficulty getting VS Code to connect with Web Debugging, double check you're not running any part of RNW (watch out for rogue
node.exe
processes) before starting the steps above.
Direct Debugging
Direct Debugging is the newer JS debugging solution for RN.
Rather than running your app's JS code on an external JS engine (as with Web Debugging), with Direct Debugging you run your app's code on its embedded engine (as normal). You are then able to attach your debugger directly to the embedded engine.
Direct Debugging requires the Metro Packager, as Metro provides keys parts of the debugging experience such as JS source mapping.
Direct Debugging Tool Support
JavaScript Engine | Edge Developer Tools | Visual Studio | Visual Studio Code | Visual Studio Code w/ React Native Tools |
---|---|---|---|---|
Chakra (Default) | 🟥 | ✅ | 🟥 | 🟥 |
Hermes | ✅ | 🟥 | ✅ | ✅ |
Important: Direct Debugging is relatively new and may still have some rough edges, depending on your choice of engine and debugger. See Web vs. Direct Debugging for details.
Step 1: Enable Direct Debugging
You have two options to enable Direct Debugging: at compile-time in your app's native code or at runtime via the in-app Developer Menu.
UseDirectDebugger
in your native code
Option 1: Setting Direct Debugging can be enabled by setting UseDirectDebugger
property of your app's InstanceSettings
during startup.
Modifying your C++ RNW app
- You'll want to edit your
App
's constructor inApp.cpp
with:
InstanceSettings().UseWebDebugger(false);
InstanceSettings().UseDirectDebugger(true);
Modifying your C# RNW app
- You'll want to edit your
App
's constructor inApp.xaml.cs
with:
InstanceSettings.UseWebDebugger = false;
InstanceSettings.UseDirectDebugger = true;
- Then simply re-build and launch your RNW app as usual.
For a new RNW app created using
react-native-windows-init
,UseDirectDebugger
defaults tofalse
.
Option 2: Using the Developer Menu
Direct Debugging can also be enabled at runtime via the in-app Developer Menu.
- With your RNW app running, press
Ctrl+Shift+D
to invoke the Developer Menu - Click Enable Direct JS Debugging
The app then should automatically refresh with Direct Debugging enabled.
Step 2: Connect a debugger
The next step is to connect with your chosen debugger.
Using the Edge Developer Tools
You can direct debug within Edge by using the Edge Developer Tools.
If you use Chrome, the process is similar for using the Chrome Developer Tools.
Launch your RNW app (with Direct Debugging enabled and Metro running)
In Edge, open the URL
edge://inspect
Make sure the box for Discover network targets is checked
Click the Configure... button next to Discover network targets
Under Target discovery settings add an entry for
localhost:8081
and click DoneRefresh the
edge://inspect
pageWatch for a Hermes React Native entry to appear in the Remote Target section at the bottom of the page. Note that the Remote Target section itself may be hidden until a valid target is detected.
Click on the inspect link under the Hermes React Native entry
You should now be able to debug your RNW application. To set breakpoints you'll first need to find your app's JS source files via Metro's source map.
- Click on the Sources tab
- Press
Ctrl+P
to invoke the Open pop-up - Find your target source file (manually or by typing its name) and open it
Make sure that the file you open is being sourced from the source map from Metro, i.e. the file entry is tagged with
localhost:8081
under the file name
You should now be able to set breakpoints in your app's JS source files.
Important: The Filesystem tab in the left sidebar normally lets you add you app's source folders to the "workspace" for easy browsing. However, files opened from the workspace will not allow you to set breakpoints correctly. You must open your app's source via the
Ctrl+P
method above for breakpoints to work.If you're trying to set a breakpoint and it's not working, double-check that the open file was opened via the source map. The tab's title should appear as an absolute file name, and its tool-tip should show the real path prefixed with
http://localhost:8081/
.
Using Visual Studio
You can direct debug RNW apps using the (default) Chakra JS engine with Visual Studio's built-in Script debugger.
Make sure you have Visual Studio installed
Open your project's Visual Studio solution file (i.e.
MyApp.sln
)Option A: Let Visual Studio launch the app and start debugging
- Make sure that Metro is already running (i.e.
npx react-native start
) - Make sure the desired Configuration (i.e.
Debug
) and Platform (i.e.x64
) of your native app by setting the drop-downs in Visual Studio's top command bar - In Solution Explorer right-click on your native app's project (i.e.
MyApp (Universal Windows)
) and select Properties- For C++ RNW apps, open the Configuration Properties > Debugging page, set the Debugger Type to Script Only, then click OK
- For C# RNW apps, open the Debug tab, set the Debugger type > Application process to Script, then close the properties
- Click on Debug in the menu bar and select Start Debugging
- Make sure that Metro is already running (i.e.
Option B: Attach Visual Studio to the app that's already running
- Make sure that your native app and Metro is already running (i.e.
npx react-native run-windows
) - Click on Debug in Visual Studio's menu bar and select Attach to Process...
- Find and select the native process for your app (not Metro)
- Make sure Attach to: is set to Automatic: Script code or Script code
If Attach to: is set to something else, double check that Script is present in the Type column for your app's process. If it isn't, make sure you've enabled Direct Debugging in your app, and click the Refresh button. If Script is present under Type but not in Attach to:, click on the Select... button and try manually checking Debug these code types: > Script.
- Click on the Attach button
- Make sure that your native app and Metro is already running (i.e.
Once everything is running, you should be able to debug your RNW application. To set breakpoints, simply do so in your app's JS source files directly in Visual Studio.
To see your app's JS source in Visual Studio, you can either:
- Open the files directly (via Open > File... in the File menu or by pressing
Ctrl+O
) OR - Looking for the files in the Solution Explorer sidebar under
Solution 'MyApp'
>Script Documents
>file://...
>script block
>http://localhost:8081/...
Using Visual Studio Code
You can direct debug RNW apps using the Hermes JS engine with VS Code's built-in Node.js debugger.
- Make sure you have VS Code installed
- Open your project's root folder in VS Code
- Click on the Run and Debug button in the sidebar or press
Ctrl+Shift+D
- Click on the drop-down at the top of the sidebar and select Add Configuration...
If there's no drop-down, click on Show all automatic debug configurations then select Add Configuration... from the drop-down that appears.
Option A: Let VS Code launch everything and start debugging
Important: This scenario isn't supported with the built-in automatic debug configurations in VS Code. If you want VS Code to launch everything for you, you'll need to install the React Native Tools extension.
Option B: Attach VS Code to Metro that's already running
- Select Node.js: Attach
- A new configuration should appear in your
launch.json
file. Rename it if you want but be sure to change theport
to8081
, i.e.:
{
"name": "Attach",
"port": 8081,
"request": "attach",
"skipFiles": [
"<node_internals>/**"
],
"type": "node"
}- Make sure that Metro is already running (i.e.
npx react-native start
) - Make sure the new config is selected at the top of the Run and Debug sidebar
- Click on the ▶️ button or press
F5
in VS Code - Confirm the address of the Metro server (default:
localhost
) - Confirm the port of the Metro server (default:
8081
)
Watch VS Code's Debug Console output for a successful debugger connection.
- Manually launch your native app (if it wasn't already running)
Once everything is running, you should be able to debug your RNW application. To set breakpoints, simply do so in your app's JS source files directly in VS Code.
Remember to save
launch.json
so you can reuse this debugging configuration in the future.
Using Visual Studio Code with the React Native Tools
You can direct debug RNW apps using the Hermes JS engine with VS Code using the React Native Tools extension.
- Make sure you have VS Code and the React Native Tools extension installed
- Open your project's root folder in VS Code
- Click on the Run and Debug button in the sidebar or press
Ctrl+Shift+D
- Click on the drop-down at the top of the sidebar and select React Native...
If there's no drop-down, click on Show all automatic debug configurations then select React Native... from the drop-down that appears.
Option A: Let VS Code launch everything and start debugging
- Click on the ⚙️ to the right of Debug Windows Hermes - Experimental
- A new configuration should appear in your
launch.json
file. Rename it if you want but it should look like:
{
"name": "Debug Windows Hermes - Experimental",
"cwd": "${workspaceFolder}",
"type": "reactnativedirect",
"request": "launch",
"platform": "windows",
"isDynamic": true
}- Make sure that Metro and your native app are not already running
- Make sure the new config is selected at the top of the Run and Debug sidebar
- Click on the ▶️ button or press
F5
in VS Code
Watch VS Code's Debug Console output for a successful debugger connection. This can be very slow, but VS Code should automatically launch Metro, establish the debugger connection, then launch your native app to download the bundle.
Option B: Attach VS Code to Metro that's already running
- Click on the ⚙️ to the right of Attach to Hermes application - Experimental
- A new configuration should appear in your
launch.json
file. Rename it if you want but it should look like:
{
"name": "Attach to Hermes application - Experimental",
"cwd": "${workspaceFolder}",
"type": "reactnativedirect",
"request": "attach",
"isDynamic": true
}- Make sure that Metro is already running (i.e.
npx react-native start
) - Make sure the new config is selected at the top of the Run and Debug sidebar
- Click on the ▶️ button or press
F5
in VS Code - Confirm the address of the Metro server (default:
localhost
) - Confirm the port of the Metro server (default:
8081
)
Watch VS Code's Debug Console output for a successful debugger connection.
- Manually launch your native app (if it wasn't already running)
Once everything is running, you should be able to debug your RNW application. To set breakpoints, simply do so in your app's JS source files directly in VS Code.
Remember to save
launch.json
so you can reuse this debugging configuration in the future.
Web vs. Direct Debugging
As mentioned above, RNW supports both Web and Direct Debugging, and it's worth knowing when to use each.
Web Debugging is the older, more well-established of the two debugging solutions. It relies on the powerful in-browser debugging tools already familiar to web developers. This reinforces RN's purpose of enabling web developers to build native apps with web technologies.
However, Web Debugging is not without its limitations. The primary problem is that JS can behave slightly differently when running in different JS engines. As such, by developing (and testing) your app while using a browser to run the JS, you might miss bugs or other issues that only manifest when running your app normally with the embedded JS engine.
This requires developers to double check all of their app's functionality in the release build, or risk situations where customers find bugs in production that aren't reproducible when using Web Debugging.
Furthermore, some parts of RN, such as synchronous calls to native module methods, only work when running on the embedded JS engine. Such native methods won't work when using Web Debugging.
With Direct Debugging, you're debugging your JS code in the same engine you ship with your final app. This removes that class of bugs caused by using a different engine while in development.
However, Direct Debugging has its own limitations too. It is newer and therefore more likely to have setup and stability issues. Furthermore, the JS debugger you want to use might not support the JS engine you want your app to use.
It is important to note, that while Web Debugging may be a sufficient for your needs now, both the RN and RNW teams are focusing future investment into the Direct Debugging experience.
Other Tools
Here are some other tools you find useful while debugging your RNW apps.
React Developer Tools
The React Developer Tools can be used to inspect your app's React component hierarchy and perform performance profiling. It works in conjunction with either Web or Direct Debugging.
- Launch your RNW app (with Metro running)
- Run
npx react-devtools
from the command line - With your RNW app running, press
Ctrl+Shift+D
to invoke the Developer Menu
The React Developer Tools should detect the Developer Menu opening and automatically attach to your app.