Add usage and simulator setup instructions (#32)

INSTALLATION.md

@@ -12,16 +12,14 @@ From the "Assets" section, download the `.vsix` file:
 
 <img width="825" alt="download-vsix" src="https://github.com/software-mansion-labs/react-native-ide/assets/726445/05f41079-9d1d-430b-a178-5c0661890687">
 
-
 ## 2. Install VSIX in vscode
 
 Open Visual Studio Code to install the downloaded extension package.
 You can [follow this official vscode guide on installing VSIX extension] to see all the possible ways how this can be handled, or navigate to extension panel and click "Install from VSIX" option that's placed under "···" button in the top right corner, then select the downloaded file.
 
 <img width="609" alt="install-from-vsix" src="https://github.com/software-mansion-labs/react-native-ide/assets/726445/1d648637-e87a-4387-ba64-8fe7ab5b6148">
 
-
-## Updating
+## Updates
 
 When installing updates, you should follow the same exact procedure and the new version will be installed over the previous one (you can also downgrade to some older version this way).
 When overinstalling new VSIX file, you'll be prompted with a dialog to reload vscode window, which you need to accept before the new version is loaded.

README.md

@@ -6,7 +6,20 @@ React Native IDE is not a ready product (yet).
 We are hoping that together with the community we will be able to get there soon.
 We are thankful that you decided to join the beta program and help us improve this tool.
 
-### ✨ What
+### 🚧 Who can use this
+
+React Native IDE currently supports some subset of React Native projects due to a number of different setup options.
+We constantly work to improve this compatibility, and in case your project structure isn’t supported feel free to open an issue.
+Below we list high-level requirements for the projects we support at the moment:
+
+- With React Native IDE you can only run iOS and Android applications. If your project supports other platforms, you should be able to use the IDE but only for launching the Android and iOS part of your project.
+- We support only recent version of React Native (0.71 onwards) as well as Expo SDK 49+
+- Brownfield-type projects are currently not supported (projects that are primarily native apps with React Native used on some screens)
+- Expo Go projects aren't currently supported
+
+As a general rule of thumb, if your projects started from Expo template or React Native community CLI template and hasn’t diverged much in terms of build configuration meaning that you can still run it using expo or react native CLI without additional steps, it should work with React Native IDE.
+
+### ✨ What does it do
 
 React Native IDE is a vscode extension that aims to streamline development of React Native and Expo applications.
 The current version supports developing for Android and iOS platforms with the current list of features available:
@@ -24,6 +37,10 @@ The current version supports developing for Android and iOS platforms with the c
 
 For installation instructions head to [INSTALLATION](INSTALLATION.md) section.
 
+### 💻 Usage
+
+See [USAGE](USAGE.md) guide on how to get started after installing the extension. You can also visit [React Native IDE](https://ide.swmansion.com) website where we hilight the most important features.
+
 ### 🐛 Troubleshooting
 
 For troubleshooting and guide on reporting issues head to [TROUBLESHOOTING](TROUBLESHOOTING.md) section.

SIMULATORS.md

@@ -0,0 +1,26 @@
+## Managing System Images for Simulators and Emulators
+
+While the IDE can manage simulator and emulator instances, it requires that the right version of system images is installed on your computer.
+
+In case when no supported image is installed, you won't be able to create new simulator or emulator using the IDE.
+Please follow below sections to learn how to install and manage system versions for Android emulators and iOS simulators.
+
+### Installing Android images
+
+1. Open Android Studio and launch SDK Manager from "Tools" menu.
+2. Lookup Android version of your choice and install one of available system images. You can use "Show Package Details" checkbox to see full list of options. It is important that you select System Image that's right for your processor (for M1/2/3 Macs select ARM 64 image, or Intel for older generations of Macs). We recommend selecting Google Play-enabled images, but this choice doesn't impact the way the extension works.
+3. Select and install the right image.
+<img width="800" alt="android-sdk-manager" src="https://github.com/software-mansion-labs/react-native-ide/assets/726445/8c078f77-1b72-477d-b4d3-dcb0b48e5851">
+
+
+### Installing iOS platforms
+
+1. Open Xcode and launch settings dialog from Xcode > Settings menu
+2. Go to "Platforms" tab:
+<img width="800" alt="ios-platforms-manager" src="https://github.com/software-mansion-labs/react-native-ide/assets/726445/edb89317-78cf-48c9-a915-c03006f8b5ca">
+
+3. Use "+" button in bottom left corner, select "iOS" from the menu and find the iOS version you want to install from the list:
+<img width="800" alt="ios-platforms-manager-select-version" src="https://github.com/software-mansion-labs/react-native-ide/assets/726445/b6cc64a8-bca7-42a3-88cd-13ef458441bb">
+
+
+4. Click "Download & install" button to begin installing

TROUBLESHOOTING.md

@@ -7,7 +7,26 @@ Below, we outline some ways that may help you self-diagnose and hopefully resolv
 This command can be located on the vscode commands palette when a given workspace is not recognized as a valid React Native of Expo project.
 In this case lookup command called "React Native IDE: Diagnostics" – when executed it will show a notification message with pointers on why React Native IDE panel cannot be opened for this project.
 
-### 2. Accessing extension logs
+### 2. Is your project setup supported?
+
+The extension does not currently support all types and configurations of React Native projects.
+For example, Expo Go or brownfield apps aren't supported while we are improving the compatibility of different project setups.
+Please refer to ["Who can use this"](README.md) section for more details on that.
+
+### 3. Can extension locate your React Native project
+
+The extension supports monorepo-type of setups and you should be able to use it even if the app isn't in the root folder of your workspace.
+This setup however has some limitations because the extension can only work with a single application per workspace.
+If your monorepo contain multiple projects, you'll need to instruct the extension with the location of your main React Native or Expo application folder.
+This can be done using vscode setting that the extension exposes – open settings and look for "Relative App Location" setting in "React Native IDE" section, and follow the instructions provided on the setting screen.
+
+### 4. List of available devices is empty
+
+The extension relies on Android Studio to install Android emulators and on Xcode tools to manage and install iOS simulators.
+The extension can spawn new devices on its own, but it requires the system images can only be installed using Android Studio and Xcode.
+Please refer to [SIMULATORS](SIMULATORS.md) section to learn more about installing system images for different platforms.
+
+### 5. Accessing extension logs
 
 In order to access React Native IDE extension logs you need to open "Output Panel" with the default shortcut ⇧⌘U or by using a command named "Developer: Show Logs..." from the command palette.
 On the "Output Panel", select "React Native IDE" as the source.
@@ -18,16 +37,17 @@ In order to share the logs with others you can use "Open Output in Editor" optio
 > This is done so that we don't need to ask you to change the log level setting that applies to all the extensions and the editor itself.
 > As a consequence you may see a lot of unnecessary messages in the log output, but we still believe it'd give us better signal when dealing with potential issues.
 
-### 3. Accessing build logs
+### 6. Accessing build logs
 
 Native builds are one of the most time consuming phases when launching your project.
 Build processes output a lot of logs on their own and hence they have separate output channels.
 When something goes wrong in the native build phase, instead of checking "React Native IDE" source in "Output Panel" as described in the previous point, select "React Native IDE (Android build)" or "React Native IDE (iOS build)" source depending on the platform you're building for.
 
-### 4. General ways of recovering in case of errors
+### 7. General ways of recovering in case of errors
 
 Here is what you can try when the extension got stuck on some errors:
 
 - Try "Clean rebuild" option from the cog-wheel menu in the upper right corner of the extension panel
 - Try closing and reopening extension panel
+- Check whether you can build and run app without the extension (using `expo` or `react-native-cli`)
 - Try restarting vscode ¯\\\_(ツ)\_/¯

USAGE.md

@@ -0,0 +1,103 @@
+After [INSTALLING](INSTALLATION.md) the extension, you should be able to start using the extension by opening your React Native or Expo project as a workspace in Visual Studio Code.
+If that's not the case and you have problems getting the extension to run, please check [TROUBLESHOOTING](TROUBLESHOOTING.md) guide.
+
+For a quick overview of the features the IDE provides, you can check [React Native IDE website](https://ide.swmansion.com).
+
+## 1. Open your project in vscode and start the extension panel
+
+If your project setup is supported, there is no extra configuration that's necessary to get the project running.
+The only thing you need to do is open your React Native of Expo project as workspace in vscode (File > Open Folder... option or using `code` command with the folder name from terminal).
+Once you have it open, you can start the extension panel in one of a few ways:
+
+1. When you open any file of your project to edit it, you can launch the extension from "Open IDE Panel" button in the editor toolbar:
+<img width="800" alt="sztudio_editor_button" src="https://github.com/software-mansion-labs/react-native-ide/assets/726445/18983660-0a06-4b56-ba3f-2eda2bf50f12">
+2. You can use "React Native IDE: Open IDE Panel" available in vscode's command palette:
+<img width="800" alt="sztudio_command_palette" src="https://github.com/software-mansion-labs/react-native-ide/assets/726445/ea7579b1-fc40-47c2-9d1c-50907ec9d665">
+3. If you already had the panel open in this project before restarting the editor, it will automatically reopen in the same place.
+
+## 2. Create simulator and emulator instances on the first run
+
+When you open the IDE panel for the first time, it'll ask you to configure Android emulator of iOS simulator.
+Depending on which platform you want to run your app on first, click one of the options available at the initial screen:
+<img width="650" alt="sztudio-init-screen" src="https://github.com/software-mansion-labs/react-native-ide/assets/726445/d2c6a55a-2f22-46fe-917b-686766ad1f8e">
+
+You will be able to add or remove simulators later using the device menu in the left bottom corner of the panel.
+
+In case the IDE cannot locate system images to use for the device, you will see an empty list when creating new emulator or simulator.
+Please follow the [SIMULATORS](SIMULATORS.md) section to learn how to manage system versions of Android emulators or iOS simulators that the IDE can use.
+
+## 3. Decide on the location of the IDE panel
+
+The main extension window can be either presented as one of the editor tabs, which is the default behavior, or as a side panel.
+To change between these two modes, open VSCode settings and search for "React Native IDE: Show Panel in Activity Bar" option.
+Note that when the extension is used as side panel it can be dragged to the secondary side panel that's on the opposite side to where your file explorer is placed:
+
+## 4. Wait for the project to build and run
+
+After all the above steps, you should be able to see your app building and launching in the extension device preview.
+From there, you can use the simulator normally to navigate in your app and try out some of the developer experience enhancements that the IDE provides.
+
+## 5. IDE featuers highlights
+
+Visit [React Native IDE](https://ide.swmansion.com/) webside, for a nicely presented list of the feature highlights.
+
+### Click to inspect
+
+Using the built-in inspector you can jump directly from preview to a file where your component is defined.
+
+<video width="500" controls>
+  <source src="packages/docs/static/video/2_sztudio_inspect.mp4" type="video/mp4">
+</video>
+
+### Use breakpoints right in VSCode
+
+Without any additional setup the extension allows to add a breakpoints in Visual Studio Code to debug your React Native application.
+IDE also automatically stops at runtime exceptions showing you the exact line of code where they happened.
+
+<video width="500" controls>
+  <source src="packages/docs/static/video/3_sztudio_debugger.mp4" type="video/mp4">
+</video>
+
+### URL bar (currently supports expo-router only)
+
+The React Native IDE integrates with your deep-linked application allowing you to jump around the navigation structure.
+
+<video width="500" controls>
+  <source src="packages/docs/static/video/4_sztudio_url_bar.mp4" type="video/mp4">
+</video>
+
+### Logs integration
+
+React Native IDE uses the built-in VSCode console allowing you to filter through the logs.
+The links displayed in the console are automatically linking back to your source code.
+
+<video width="500" controls>
+  <source src="packages/docs/static/video/5_sztudio_logs_panel.mp4" type="video/mp4">
+</video>
+
+### Develop components in isolation
+
+Develop your components individually without distractions.
+
+Install `react-native-ide` package and use `preview` method from it to define the components that should render in preview mode:
+
+```js
+import { preview } from 'react-native-ide';
+
+preview(<MyComponent param={42} />);
+```
+
+The extension will display a clickable "Open preview" button over the line with `preview` call that you can use to launch into the preview mode.
+
+<video width="500" controls>
+  <source src="packages/docs/static/video/6_sztudio_preview.mp4" type="video/mp4">
+</video>
+
+### Adjust device settings on the fly
+
+You can adjust text size and light/dark mode right from the React Native IDE.
+Focus just on your app without switching between windows.
+
+<video width="500" controls>
+  <source src="packages/docs/static/video/7_sztudio_device_settings.mp4" type="video/mp4">
+</video>

packages/docs/src/components/Sections/Overview/index.tsx

@@ -20,7 +20,7 @@ const items = [
   },
   {
     title: "Navigation made easier",
-    body: "The React Native IDE integrates tightly with your deep-linked application allowing you to jump around the navigation structure. Supports both Expo Router and React Navigation projects.",
+    body: "The React Native IDE integrates tightly with your deep-linked application allowing you to jump around the navigation structure (supports Expo Router projects).",
     mediaSrc: "video/4_sztudio_url_bar.mp4",
   },
   {