Walkthroughs implementation (microsoft#1698)

* Add docs about element inspector

* Implement walkthroughs feature

Co-authored-by: RedMickey <[email protected]>
Co-authored-by: RedMickey <[email protected]>

README.md

@@ -20,7 +20,7 @@ To avoid conflicts, if both extensions are installed - the only stable version w
 This VS Code extension provides a development environment for React Native projects.
 Using this extension, you can **debug your code and quickly run `react-native` commands** from the command palette.
 
-![React Native features](images/react-features.gif)
+![React Native features](resources/images/react-features.gif)
 
 <!-- TABLE OF CONTENTS -->
 
@@ -54,6 +54,7 @@ Using this extension, you can **debug your code and quickly run `react-native` c
   - [Configure an Android LogCat Monitor](#configure-an-android-logcat-monitor)
   - [Configure dependencies versions for debugging Expo projects](#configure-dependencies-versions-for-debugging-expo-projects)
   - [Configure custom key bindings for extension commands](#configure-custom-key-bindings-for-extension-commands)
+- [Element inspector](#element-inspector)
 - [Network Inspector](#network-inspector)
 - [Developing inside a Docker Container](#developing-inside-a-docker-container)
 - [Contributing](#contributing)
@@ -74,7 +75,7 @@ Please notice that the extension uses `.vscode/.react` directory at the project
 
 In the Command Palette, type `React Native` and choose a command.
 
-![React Native commands](images/command-palette.png)
+![React Native commands](resources/images/command-palette.png)
 
 The **Run Android** command triggers `react-native run-android` and starts your app for Android.
 
@@ -129,33 +130,33 @@ To run React Native Tools commands via VS Code tasks, you can create a `.vscode/
 
 To 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 then selecting `React Native` option. After that the extension will prompt you to create a debugging configuration by selecting debugging parameters in dropdown lists at the top of the editor. A new debugging configuration will be generated and added to the `launch.json` file automatically as shown in the image below.
 
-![Add React Native debug configuration](images/add-debug-configuration.gif)
+![Add React Native debug configuration](resources/images/add-debug-configuration.gif)
 
-In 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.
+In 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](resources/images/debug-view-icon.png) in the View bar, and then click the configuration (gear) icon ![Configure-gear](resources/images/configure-gear-icon.png), then choose the React Native debug environment.
 
-![Choose React Native debugger](images/choose-debugger.png)
+![Choose React Native debugger](resources/images/choose-debugger.png)
 
-VS 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.
+VS 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](resources/images/debug-icon.png) button) to start debugging your app in VS Code.
 
-![React Native launch targets](images/debug-targets.png)
+![React Native launch targets](resources/images/debug-targets.png)
 
 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 degub 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.
 
-  ![Run dynamic debugging configuration](images/dynamic-debugging-configuration.gif)
+  ![Run dynamic debugging configuration](resources/images/dynamic-debugging-configuration.gif)
 
 - 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.
 
-  ![Select and run debugging command](images/debug-commands-button.png)
+  ![Select and run debugging command](resources/images/debug-commands-button.png)
 
 Once 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.
 
-![React Native enable remote debug](images/enable-remote-debug.png)
+![React Native enable remote debug](resources/images/enable-remote-debug.png)
 
 The extension allows you to debug multiple devices and configurations, please read the following sections for more information for your particular use case.
 
@@ -316,7 +317,7 @@ To start debugging in Expo follow these steps:
 1. 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.
 1. 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.
 
-   ![React Native developer menu](./images/enable-remote-debug.png)
+   ![React Native developer menu](./resources/images/enable-remote-debug.png)
 
    From here you can run and debug the app as normal.
 
@@ -682,11 +683,11 @@ module.exports = {
 <details>
 <summary>Port setup instruction</summary>
 
-![image](images/select-dev-menu.png)
+![image](resources/images/select-dev-menu.png)
 
-![image](images/dev-menu-setup-custom-host.png)
+![image](resources/images/dev-menu-setup-custom-host.png)
 
-![image](images/custom-host-and-port.png)
+![image](resources/images/custom-host-and-port.png)
 
 </details>
 
@@ -775,13 +776,32 @@ The extension provides context variables for the following features:
 |`isRNTNetworkInspectorRunning` - true if the Network inspector is running|Network inspector|
 
 Using these context variables you can assign the same keyboard combination for some pair commands for more convenient use. For example, you can configure the same key bindings for `Start Packager` and `Stop Packager` commands using `when` clauses, as shown below:
-![image](images/custom-keybindings.png)
+![image](resources/images/custom-keybindings.png)
+
+# Element inspector
+
+In the extension you can run React DevTools Element inspector to inspect the DOM-tree of your application.
+It's required to install the [`react-devtools`](https://www.npmjs.com/package/react-devtools) package globally to run React DevTools from the extension.
+
+```
+npm install -g react-devtools
+```
+
+### Integration with React Native Inspector
+
+You can open the in-app developer menu and choose "Show Element Inspector". It will bring up an overlay that lets you tap on any UI element and see information about it:
+
+![Element inspector usage](resources/images/element-inspector-usage.gif)
+
+Using the `Run Element Inspector` Command Palette command you can launch React DevTools in the extension. Inspector will enter a special collapsed mode, and use the DevTools as primary UI. In this mode, clicking on something in the emulator will bring up the relevant components in the DevTools:
+
+![Element inspector usage](resources/images/element-inspector-with-ui.png)
 
 # Network Inspector
 
 The extension provides `Network inspector` feature to inspect outgoing network traffic in your apps. You can browse all requests being made and their responses in VS Code DevTools console.
 
-![image](images/network-inspector.png)
+![image](resources/images/network-inspector.png)
 
 ### Network inspector requirements
 

package.json

@@ -4,7 +4,7 @@
   "version": "1.8.1",
   "private": true,
   "publisher": "msjsdiag",
-  "icon": "images/icon.png",
+  "icon": "resources/images/icon.png",
   "galleryBanner": {
     "color": "#3B3738",
     "theme": "dark"
@@ -49,6 +49,76 @@
   ],
   "main": "./src/extension/rn-extension",
   "contributes": {
+    "walkthroughs": [
+      {
+        "id": "RNTGetStarted",
+        "title": "Get started with React Native development",
+        "description": "Your first steps to set up the environment for React Native development and explore the extension functionality",
+        "steps": [
+          {
+            "id": "settingUpCommonEnvironment",
+            "title": "Set up RN development environment",
+            "description": "To develop React Native applications in the React Native Tools extension, you need to set up your development environment in accordance with the requirements of React Native.\n[Learn more](https://reactnative.dev/docs/environment-setup)",
+            "media": {
+              "markdown": "resources/walkthougths/setup-env-common.md"
+            }
+          },
+          {
+            "id": "settingUpExpoEnvironment",
+            "title": "Prepare for Expo development",
+            "description": "The extension provides functionality for developing Expo applications. To get started, you need to set up the development environment in accordance with the extension requirements.\n[Learn more](https://github.com/microsoft/vscode-react-native#expo-applications)",
+            "media": {
+              "markdown": "resources/walkthougths/setup-env-expo.md"
+            }
+          },
+          {
+            "id": "settingUpWindowsEnvironment",
+            "title": "Prepare for React Native for Windows",
+            "description": "To develop React Native for Windows applications, you need to set up your dev environment in accordance with the [official requirements](https://microsoft.github.io/react-native-windows/docs/rnw-dependencies).",
+            "when": "isWindows",
+            "media": {
+              "image": "resources/images/rnw-set-up.png",
+              "altText": "React Native for Windows app view"
+            }
+          },
+          {
+            "id": "settingUpMacOsEnvironment",
+            "title": "Prepare for React Native for macOS",
+            "description": "To develop React Native for macOS applications, you need to set up your dev environment in accordance with the [official requirements](https://microsoft.github.io/react-native-windows/docs/rnm-dependencies).",
+            "when": "isMac",
+            "media": {
+              "image": "resources/images/rnm-set-up.png",
+              "altText": "React Native for macOS app view"
+            }
+          },
+          {
+            "id": "hermesEngine",
+            "title": "Hermes Engine",
+            "description": "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.\n[Learn more](https://github.com/microsoft/vscode-react-native#hermes-engine)",
+            "media": {
+              "image": "resources/images/hermeslogo.svg",
+              "altText": "Hermes logo"
+            }
+          },
+          {
+            "id": "runAndDebugReactNativeApp",
+            "title": "Run and Debug your React Native application",
+            "description": "Create a debug configuration and start debugging your React Native application.\n[Learn more](https://github.com/microsoft/vscode-react-native#debugging-react-native-applications)",
+            "media": {
+              "markdown": "resources/walkthougths/debug-tutor.md"
+            }
+          },
+          {
+            "id": "exploreExtensionFeatures",
+            "title": "Explore extension features",
+            "description": "The extension provides useful features to facilitate the development of React Native applications.\n[Learn more](https://github.com/microsoft/vscode-react-native#customization)",
+            "media": {
+              "markdown": "resources/walkthougths/features-tutor.md"
+            }
+          }
+        ]
+      }
+    ],
     "commands": [
       {
         "command": "reactNative.launchAndroidSimulator",

resources/walkthougths/debug-tutor.md

@@ -0,0 +1,23 @@
+# Run and Debug your React Native application
+## Create and run debugging scenario
+This extension supports generating debugging configuration in the `.vscode/launch.json` file by selecting debugging parameters in dropdown lists at the top of the editor.
+
+![Add React Native debug configuration](../images/add-debug-configuration.gif)
+
+To start debugging, just 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.
+
+The extension also allows to start debugging without creating the `launch.json` file in one of the following ways:
+- Using dynamic debugging configurations
+
+    ![Run dynamic debugging configuration](../images/dynamic-debugging-configuration.gif)
+- Using Debug button in the Editor Title area menu
+
+    ![Select and run debugging command](../images/debug-commands-button.png)
+
+## Enable debugging mode and attach to the application
+After using one of the suggested methods of launching the application, wait for the application to launch.
+
+Once 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. After that, please wait until the extension attaches to your application.
+
+![React Native enable remote debug](../images/enable-remote-debug.png)
+

resources/walkthougths/features-tutor.md

@@ -0,0 +1,9 @@
+# Main extension features
+## React Native commands in the Command Palette
+The extension provides special `Command Palette commands` for running React Native applications on different platforms, operating with the Packager and automating some dev processes. You can find more info about supported commands [here](https://github.com/microsoft/vscode-react-native#react-native-commands-in-the-command-palette).
+## Network inspector
+The extension provides `Network inspector` feature to inspect outgoing network traffic in your apps. You can browse all requests being made and their responses in VS Code DevTools console. More details about Network inspector usage and its requirements are available [here](https://github.com/microsoft/vscode-react-native#network-inspector) in the documentation.
+## Element inspector
+In the extension you can run React DevTools Element inspector to inspect the DOM-tree of your application by starting `Run Element Inspector` command in Command Palette. You can learn more about React DevTools installation and usage [here](https://github.com/microsoft/vscode-react-native#element-inspector).
+## Customization
+The extension provides different settings that can be customized according to personal preferences to improve the extension usability. Please see the [Customization](https://github.com/microsoft/vscode-react-native#customization) section in the documentation.

resources/walkthougths/setup-env-common.md

@@ -0,0 +1,10 @@
+# Getting started
+Before going any further, please check out the following information to help you get started with React Native Tools successfully.
+
+Make sure that you:
+
+- [have a working React Native environment](https://reactnative.dev/docs/environment-setup).
+- have the [`emulator`](https://developer.android.com/studio/run/emulator-commandline) utility available in your `PATH` if you're developing Android applications using emulators.
+- have your React Native project root folder open in VS Code.
+
+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.

resources/walkthougths/setup-env-expo.md

@@ -0,0 +1,10 @@
+# Expo applications
+Prepare your environment by following the [Expo CLI Quickstart instruction](https://reactnative.dev/docs/environment-setup).
+For correct work with Expo this extension **`requires Android SDK`**.
+So also pay attention to the `React Native CLI Quickstart` tab, where you can find the Android SDK installation guide:
+
+- Install the [Expo app](https://docs.expo.dev/get-started/installation/#2-expo-go-app-for-ios-and) on the target device or emulator
+- 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))
+- Ensure that the `expo-cli` is installed globally (`npm install -g expo-cli`)
+
+You can verify that everything is working correctly and that the environment is ready for use with the `npx react-native doctor` command.