More docs & helptext cleanup (#5229)

* wip

* Flesh out resolution docs

* Polish

* More

* WIP

* WIP

* WIP

* Document --watch

10 files changed, 133 insertions, 18 deletions

diff --git a/docs/api/file-io.md b/docs/api/file-io.md
index e6902cc6a..f37473c33 100644
--- a/docs/api/file-io.md
+++ b/docs/api/file-io.md
@@ -2,7 +2,7 @@
 
 <!-- **Note** — The `Bun.file` and `Bun.write` APIs documented on this page are heavily optimized and represent the recommended way to perform file-system tasks using Bun. Existing Node.js projects may use Bun's [nearly complete](/docs/runtime/nodejs-apis#node-fs) implementation of the [`node:fs`](https://nodejs.org/api/fs.html) module. -->
 
-**Note** — The `Bun.file` and `Bun.write` APIs documented on this page are heavily optimized and represent the recommended way to perform file-system tasks using Bun. For operations that are not yet available with `Bun.file`, such as `mkdir`, you can use Bun's [nearly complete](/docs/runtime/nodejs-apis#node-fs) implementation of the [`node:fs`](https://nodejs.org/api/fs.html) module.
+**Note** — The `Bun.file` and `Bun.write` APIs documented on this page are heavily optimized and represent the recommended way to perform file-system tasks using Bun. For operations that are not yet available with `Bun.file`, such as `mkdir` or `readdir`, you can use Bun's [nearly complete](/docs/runtime/nodejs-apis#node-fs) implementation of the [`node:fs`](https://nodejs.org/api/fs.html) module.
 
 {% /callout %}
 
diff --git a/docs/bundler/index.md b/docs/bundler/index.md
index 585a6ac52..8db531ce5 100644
--- a/docs/bundler/index.md
+++ b/docs/bundler/index.md
@@ -132,6 +132,14 @@ Visit `http://localhost:5000` to see your bundled app in action.
 
 {% /details %}
 
+## Watch mode
+
+Like the runtime and test runner, the bundler supports watch mode natively.
+
+```sh
+$ bun build ./index.tsx --outdir ./out --watch
+```
+
 ## Content types
 
 Like the Bun runtime, the bundler supports an array of file types out of the box. The following table breaks down the bundler's set of standard "loaders". Refer to [Bundler > File types](/docs/runtime/loaders) for full documentation.
diff --git a/docs/bundler/vs-esbuild.md b/docs/bundler/vs-esbuild.md
index 44ab835a3..67bed3dc3 100644
--- a/docs/bundler/vs-esbuild.md
+++ b/docs/bundler/vs-esbuild.md
@@ -130,8 +130,8 @@ In Bun's CLI, simple boolean flags like `--minify` do not accept an argument. Ot
 ---
 
 - `--watch`
-- n/a
-- Not applicable
+- `--watch`
+- No differences
 
 ---
 
diff --git a/docs/guides/ecosystem/nextjs.md b/docs/guides/ecosystem/nextjs.md
index a455eb23e..4d3be8cfc 100644
--- a/docs/guides/ecosystem/nextjs.md
+++ b/docs/guides/ecosystem/nextjs.md
@@ -3,7 +3,7 @@ name: Build an app with Next.js and Bun
 ---
 
 {% callout %}
-Next.js currently relies on Node.js APIs that Bun does not yet implement. The guide below uses Bun to initialize a project and install dependencies, but it uses Node.js to run the dev server.
+The Next.js [App Router](https://nextjs.org/docs/app) currently relies on Node.js APIs that Bun does not yet implement. The guide below uses Bun to initialize a project and install dependencies, but it uses Node.js to run the dev server.
 {% /callout %}
 
 ---
@@ -23,7 +23,16 @@ Creating a new Next.js app in /path/to/my-app.
 
 ---
 
-To start the dev server, run `bun run dev` from the project root.
+To start the dev server with Bun, run `bun --bun run dev` from the project root.
+
+```sh
+$ cd my-app
+$ bun --bun run dev
+```
+
+---
+
+To run the dev server with Node.js instead, omit `--bun`.
 
 ```sh
 $ cd my-app
diff --git a/docs/guides/install/registry-scope.md b/docs/guides/install/registry-scope.md
index 48f7dee79..68d8cf942 100644
--- a/docs/guides/install/registry-scope.md
+++ b/docs/guides/install/registry-scope.md
@@ -11,7 +11,11 @@ Bun does not read `.npmrc` files; instead private registries are configured via
 
 # as an object with username/password
 # you can reference environment variables
-"@myorg2" = { username = "myusername", password = "$npm_pass", url = "https://registry.myorg.com/" }
+"@myorg2" = {
+  username = "myusername",
+  password = "$npm_pass",
+  url = "https://registry.myorg.com/"
+}
 
 # as an object with token
 "@myorg3" = { token = "$npm_token", url = "https://registry.myorg.com/" }
diff --git a/docs/guides/install/workspaces.md b/docs/guides/install/workspaces.md
index f87c1e337..4628d6aaa 100644
--- a/docs/guides/install/workspaces.md
+++ b/docs/guides/install/workspaces.md
@@ -4,6 +4,8 @@ name: Configuring a monorepo using workspaces
 
 Bun's package manager supports npm `"workspaces"`. This allows you to split a codebase into multiple distinct "packages" that live in the same repository, can depend on each other, and (when possible) share a `node_modules` directory.
 
+Clone [this sample project](https://github.com/colinhacks/bun-workspaces) to experiment with workspaces.
+
 ---
 
 The root `package.json` should not contain any `"dependencies"`, `"devDependencies"`, etc. Each individual package should be self-contained and declare its own dependencies. Similarly, it's conventional to declare `"private": true` to avoid accidentally publishing the root package to `npm`.
@@ -37,7 +39,7 @@ It's common to place all packages in a `packages` directory. The `"workspaces"`
 
 To add one workspace as a dependency of another, modify its `package.json`. Here we're adding `stuff-a` as a dependency of `stuff-b`.
 
-```json#packages/stuff-b/package.json
+```json-diff#packages/stuff-b/package.json
 {
   "name": "stuff-b",
   "dependencies": {
diff --git a/docs/guides/runtime/typescript.md b/docs/guides/runtime/typescript.md
new file mode 100644
index 000000000..f6afe02c1
--- /dev/null
+++ b/docs/guides/runtime/typescript.md
@@ -0,0 +1,69 @@
+---
+name: Install TypeScript declarations for Bun
+---
+
+To install TypeScript definitions for Bun's built-in APIs in your project, install `bun-types`.
+
+```sh
+$ bun add -d bun-types # dev dependency
+```
+
+---
+
+Then include `"bun-types"` in the `compilerOptions.types` in your `tsconfig.json`:
+
+```json-diff
+  {
+    "compilerOptions": {
++     "types": ["bun-types"]
+    }
+  }
+```
+
+---
+
+Unfortunately, setting a value for `"types"` means that TypeScript will ignore other global type definitions, including `lib: ["dom"]`. If you need to add DOM types into your project, add the following [triple-slash directives](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html) at the top of any TypeScript file in your project.
+
+```ts
+/// <reference lib="dom" />
+/// <reference lib="dom.iterable" />
+```
+
+---
+
+Below is the full set of recommended `compilerOptions` for a Bun project. With this `tsconfig.json`, you can use top-level await, extensioned or extensionless imports, and JSX.
+
+```jsonc
+{
+  "compilerOptions": {
+    // add Bun type definitions
+    "types": ["bun-types"],
+
+    // enable latest features
+    "lib": ["esnext"],
+    "module": "esnext",
+    "target": "esnext",
+
+    // if TS 5.x+
+    "moduleResolution": "bundler",
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "moduleDetection": "force",
+    // if TS 4.x or earlier
+    // "moduleResolution": "nodenext",
+
+    "jsx": "react-jsx", // support JSX
+    "allowJs": true, // allow importing `.js` from `.ts`
+    "esModuleInterop": true, // allow default imports for CommonJS modules
+
+    // best practices
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+---
+
+Refer to [Ecosystem > TypeScript](/docs/runtime/typescript) for a complete guide to TypeScript support in Bun.
diff --git a/docs/installation.md b/docs/installation.md
index df4d12cea..c0b823623 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -10,6 +10,8 @@ Bun ships as a single executable that can be installed a few different ways.
 
 ```bash#macOS/Linux_(curl)
 $ curl -fsSL https://bun.sh/install | bash # for macOS, Linux, and WSL
+# to install a specific version
+$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.0.0"
 ```
 
 ```bash#NPM
diff --git a/docs/runtime/modules.md b/docs/runtime/modules.md
index a876a5a2b..fe8bb8c64 100644
--- a/docs/runtime/modules.md
+++ b/docs/runtime/modules.md
@@ -184,18 +184,38 @@ Once it finds the `foo` package, Bun reads the `package.json` to determine how t
 
 Whichever one of these conditions occurs _first_ in the `package.json` is used to determine the package's entrypoint.
 
-Bun respects subpath [`"exports"`](https://nodejs.org/api/packages.html#subpath-exports) and [`"imports"`](https://nodejs.org/api/packages.html#imports). Specifying any subpath in the `"exports"` map will prevent other subpaths from being importable.
+Bun respects subpath [`"exports"`](https://nodejs.org/api/packages.html#subpath-exports) and [`"imports"`](https://nodejs.org/api/packages.html#imports).
 
 ```jsonc#package.json
 {
   "name": "foo",
   "exports": {
-    ".": "./index.js",
-    "./package.json": "./package.json" // subpath
+    ".": "./index.js"
   }
 }
 ```
 
+Subpath imports and conditional imports work in conjunction with each other.
+
+```
+{
+  "name": "foo",
+  "exports": {
+    ".": {
+      "import": "./index.mjs",
+      "require": "./index.js"
+    }
+  }
+}
+```
+
+As in Node.js, Specifying any subpath in the `"exports"` map will prevent other subpaths from being importable; you can only import files that are explicitly exported. Given the `package.json` above:
+
+```ts
+import stuff from "foo"; // this works
+import stuff from "foo/index.mjs"; // this doesn't
+```
+
 {% callout %}
 **Shipping TypeScript** — Note that Bun supports the special `"bun"` export condition. If your library is written in TypeScript, you can publish your (un-transpiled!) TypeScript files to `npm` directly. If you specify your package's `*.ts` entrypoint in the `"bun"` condition, Bun will directly import and execute your TypeScript source files.
 {% /callout %}
diff --git a/src/cli.zig b/src/cli.zig
index 889da9320..6f05bd8cb 100644
--- a/src/cli.zig
+++ b/src/cli.zig
@@ -75,6 +75,7 @@ pub const Cli = struct {
                         \\  <cyan>--target<r>             The intended execution environment for the bundle.
                         \\                       ("browser", "bun" or "node")
                         \\  <cyan>--splitting<r>          Enable code splitting (requires --outdir)
+                        \\  <cyan>--watch<r>              Run bundler in watch mode
                         \\
                         \\<b>Examples:<r>
                         \\  <d>Frontend web apps:<r>
@@ -168,7 +169,7 @@ pub const Arguments = struct {
         clap.parseParam("-h, --help                        Display this help and exit.") catch unreachable,
         clap.parseParam("-b, --bun                         Force a script or package to use Bun's runtime instead of Node.js (via symlinking node)") catch unreachable,
         clap.parseParam("--cwd <STR>                       Absolute path to resolve files & entry points from. This just changes the process' cwd.") catch unreachable,
-        clap.parseParam("-c, --config <PATH>?              Config file to load bun from (e.g. -c bunfig.toml") catch unreachable,
+        clap.parseParam("-c, --config <PATH>?              Config file to load Bun from (e.g. -c bunfig.toml") catch unreachable,
         clap.parseParam("--extension-order <STR>...        Defaults to: .tsx,.ts,.jsx,.js,.json ") catch unreachable,
         clap.parseParam("--jsx-factory <STR>               Changes the function called when compiling JSX elements using the classic JSX runtime") catch unreachable,
         clap.parseParam("--jsx-fragment <STR>              Changes the function called when compiling JSX fragments") catch unreachable,
@@ -184,7 +185,7 @@ pub const Arguments = struct {
         clap.parseParam("-e, --external <STR>...           Exclude module from transpilation (can use * wildcards). ex: -e react") catch unreachable,
         clap.parseParam("-l, --loader <STR>...             Parse files with .ext:loader, e.g. --loader .js:jsx. Valid loaders: js, jsx, ts, tsx, json, toml, text, file, wasm, napi") catch unreachable,
         clap.parseParam("-u, --origin <STR>                Rewrite import URLs to start with --origin. Default: \"\"") catch unreachable,
-        clap.parseParam("-p, --port <STR>                  Port to serve bun's dev server on. Default: \"3000\"") catch unreachable,
+        clap.parseParam("-p, --port <STR>                  Port to serve Bun's dev server on. Default: \"3000\"") catch unreachable,
         clap.parseParam("--smol                            Use less memory, but run garbage collection more often") catch unreachable,
         clap.parseParam("--minify                          Minify (experimental)") catch unreachable,
         clap.parseParam("--minify-syntax                   Minify syntax and inline data (experimental)") catch unreachable,
@@ -201,13 +202,13 @@ pub const Arguments = struct {
     // note: we are keeping --port and --origin as it can be reused for bun
     // build and elsewhere
     pub const not_bun_dev_flags = [_]ParamType{
-        clap.parseParam("--hot                             Enable auto reload in bun's JavaScript runtime") catch unreachable,
-        clap.parseParam("--watch                           Automatically restart bun's JavaScript runtime on file change") catch unreachable,
-        clap.parseParam("--no-install                      Disable auto install in bun's JavaScript runtime") catch unreachable,
-        clap.parseParam("-i                                Automatically install dependencies and use global cache in bun's runtime, equivalent to --install=fallback") catch unreachable,
+        clap.parseParam("--hot                             Enable auto reload in the Bun runtime, test runner, or bundler") catch unreachable,
+        clap.parseParam("--watch                           Automatically restart the process on file change") catch unreachable,
+        clap.parseParam("--no-install                      Disable auto install in the Bun runtime") catch unreachable,
+        clap.parseParam("-i                                Automatically install dependencies and use global cache in Bun's runtime, equivalent to --install=fallback") catch unreachable,
         clap.parseParam("--install <STR>                   Install dependencies automatically when no node_modules are present, default: \"auto\". \"force\" to ignore node_modules, fallback to install any missing") catch unreachable,
-        clap.parseParam("--prefer-offline                  Skip staleness checks for packages in bun's JavaScript runtime and resolve from disk") catch unreachable,
-        clap.parseParam("--prefer-latest                   Use the latest matching versions of packages in bun's JavaScript runtime, always checking npm") catch unreachable,
+        clap.parseParam("--prefer-offline                  Skip staleness checks for packages in the Bun runtime and resolve from disk") catch unreachable,
+        clap.parseParam("--prefer-latest                   Use the latest matching versions of packages in the Bun runtime, always checking npm") catch unreachable,
         clap.parseParam("--silent                          Don't repeat the command for bun run") catch unreachable,
     };