Update --watch docs

1 files changed, 24 insertions, 19 deletions

diff --git a/docs/runtime/hot.md b/docs/runtime/hot.md
index 406a83d19..7e3fd3afc 100644
--- a/docs/runtime/hot.md
+++ b/docs/runtime/hot.md
@@ -7,23 +7,34 @@ Bun supports two kinds of automatic reloading via CLI flags:
 
 Watch mode can be used with `bun test` or when running TypeScript, JSX, and JavaScript files.
 
-`--watch` looks at every file that is imported by the entrypoint (or tests) and watches them for changes. When a change is detected, Bun restarts the process, using the same arguments and environment variables that initially started the process. Additionally, incase Bun crashes, `--watch` will attempt to automatically restart the process.
+To run a file in `--watch` mode:
 
-#### watching tests with `bun test`
+```bash
+$ bun index.tsx --watch
+```
 
-To watch tests with `bun test`, pass the `--watch` flag.
+To run your tests in `--watch` mode:
 
 ```bash
 $ bun test --watch
 ```
 
-![bun test gif](https://user-images.githubusercontent.com/709451/228396976-38a23864-4a1d-4c96-87cc-04e5181bf459.gif)
+In `--watch` mode, Bun keeps track of all imported files and watches them for changes. When a change is detected, Bun restarts the process, preserving the¸ same set of CLI arguments and environment variables used in the initial run. If Bun crashes, `--watch` will attempt to automatically restart the process.
 
-#### watching JavaScript and TypeScript files
+{% callout %}
+
+**⚡️ Reloads are fast.** The filesystem watchers you're probably used to have several layers of libraries wrapping the native APIs or worse, rely on polling.
 
-To watch executed code, pass the `--watch` flag to `bun` or `bun run`.
+Instead, Bun uses operating system native filesystem watcher APIs like kqueue or inotify to detect changes to files. Bun also does a number of optimizations to enable it scale to larger projects (such as setting a high rlimit for file descriptors, statically allocated file path buffers, reuse file descriptors when possible, etc).
 
-Example script:
+{% /callout %}
+The following examples shows real-time reloading using the [save-on-keypress](https://code.visualstudio.com/docs/editor/codebasics#_save-auto-save) plugin for VSCode, which saves the current file on each keystroke.
+
+{% codetabs %}
+
+```bash
+$ bun run watchy.tsx --watch
+```
 
 ```tsx#watchy.tsx
 import { serve } from "bun";
@@ -38,23 +49,17 @@ serve({
 });
 ```
 
-Run the file with `--watch`:
-
-```bash
-$ bun --watch ./watchy.tsx
-```
+{% /codetabs %}
 
 ![bun watch gif](https://user-images.githubusercontent.com/709451/228439002-7b9fad11-0db2-4e48-b82d-2b88c8625625.gif)
 
-{% details summary="Why is it fast?" %}
-
-The filesystem watchers you're probably used to have several layers of libraries wrapping the native APIs or worse, rely on polling.
-
-Instead, Bun uses operating system native filesystem watcher APIs like kqueue or inotify to detect changes to files. Bun also does a number of optimizations to enable it scale to larger projects (such as setting a high rlimit for file descriptors, statically allocated file path buffers, reuse file descriptors when possible, etc).
+Running `bun test` in watch mode and `save-on-keypress` enabled:
 
-{% /details %}
+```bash
+$ bun test --watch
+```
 
-For maximum speed, enable [save-on-keypress](https://code.visualstudio.com/docs/editor/codebasics#_save-auto-save) in your editor. This will save the file as you type, which will trigger a restart of Bun's process.
+![bun test gif](https://user-images.githubusercontent.com/709451/228396976-38a23864-4a1d-4c96-87cc-04e5181bf459.gif)
 
 ## `--hot` mode