diff options
| -rw-r--r-- | docs/runtime/hot.md | 43 |
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 ``` - +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 %}  -{% 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. + ## `--hot` mode |