minor guide fixes for consistency (#16273)

docs/api/file-io.md

@@ -62,6 +62,14 @@ Bun.stdout;
 Bun.stderr;
 ```
 
+### Deleting files (`file.delete()`)
+
+You can delete a file by calling the `.delete()` function.
+
+```ts
+await Bun.file("logs.json").delete()
+```
+
 ## Writing files (`Bun.write()`)
 
 `Bun.write(destination, data): Promise<number>`

docs/cli/install.md

@@ -15,10 +15,10 @@ If you're using Ubuntu 20.04, here's how to install a [newer kernel](https://wik
 
 ```bash
 # If this returns a version >= 5.6, you don't need to do anything
-uname -r
+$ uname -r
 
 # Install the official Ubuntu hardware enablement kernel
-sudo apt install --install-recommends linux-generic-hwe-20.04
+$ sudo apt install --install-recommends linux-generic-hwe-20.04
 ```
 
 {% /details %}
@@ -229,7 +229,7 @@ jobs:
       - name: Checkout repo
         uses: actions/checkout@v4
       - name: Install bun
-        uses: oven-sh/setup-bun@v1
+        uses: oven-sh/setup-bun@v2
       - name: Install dependencies
         run: bun install
       - name: Build app

docs/guides/ecosystem/discordjs.md

@@ -4,18 +4,18 @@ name: Create a Discord bot
 
 Discord.js works out of the box with Bun. Let's write a simple bot. First create a directory and initialize it with `bun init`.
 
-```bash
-mkdir my-bot
-cd my-bot
-bun init
+```sh
+$ mkdir my-bot
+$ cd my-bot
+$ bun init
 ```
 
 ---
 
 Now install Discord.js.
 
-```bash
-bun add discord.js
+```sh
+$ bun add discord.js
 ```
 
 ---
@@ -67,7 +67,7 @@ client.login(process.env.DISCORD_TOKEN);
 
 Now we can run our bot with `bun run`. It may take a several seconds for the client to initialize the first time you run the file.
 
-```bash
+```sh
 $ bun run bot.ts
 Ready! Logged in as my-bot#1234
 ```

docs/guides/ecosystem/hono.md

@@ -17,7 +17,7 @@ export default app;
 
 Use `create-hono` to get started with one of Hono's project templates. Select `bun` when prompted for a template.
 
-```bash
+```sh
 $ bun create hono myapp
 ✔ Which template do you want to use? › bun
 cloned honojs/starter#main to /path/to/myapp
@@ -30,7 +30,7 @@ $ bun install
 
 Then start the dev server and visit [localhost:3000](http://localhost:3000).
 
-```bash
+```sh
 $ bun run dev
 ```
 

docs/guides/ecosystem/mongoose.md

@@ -8,18 +8,18 @@ MongoDB and Mongoose work out of the box with Bun. This guide assumes you've alr
 
 Once MongoDB is running, create a directory and initialize it with `bun init`.
 
-```bash
-mkdir mongoose-app
-cd mongoose-app
-bun init
+```sh
+$ mkdir mongoose-app
+$ cd mongoose-app
+$ bun init
 ```
 
 ---
 
 Then add Mongoose as a dependency.
 
-```bash
-bun add mongoose
+```sh
+$ bun add mongoose
 ```
 
 ---

docs/guides/ecosystem/nextjs.md

@@ -15,6 +15,8 @@ $ bun create next-app
 Creating a new Next.js app in /path/to/my-app.
 ```
 
+---
+
 You can specify a starter template using the `--example` flag.
 
 ```sh

docs/guides/ecosystem/render.md

@@ -16,17 +16,17 @@ As an example, let's deploy a simple Express HTTP server to Render.
 
 Create a new GitHub repo named `myapp`. Git clone it locally.
 
-```bash
-git clone git@github.com:my-github-username/myapp.git
-cd myapp
+```sh
+$ git clone git@github.com:my-github-username/myapp.git
+$ cd myapp
 ```
 
 ---
 
 Add the Express library.
 
-```bash
-bun add express
+```sh
+$ bun add express
 ```
 
 ---
@@ -52,10 +52,10 @@ app.listen(port, () => {
 
 Commit your changes and push to GitHub.
 
-```bash
-git add app.ts bun.lockb package.json
-git commit -m "Create simple Express app"
-git push origin main
+```sh
+$ git add app.ts bun.lockb package.json
+$ git commit -m "Create simple Express app"
+$ git push origin main
 ```
 
 ---

docs/guides/ecosystem/sentry.md

@@ -10,8 +10,8 @@ Don't already have an account and Sentry project established? Head over to [sent
 
 To start using Sentry with Bun, first install the Sentry Bun SDK.
 
-```bash
-bun add @sentry/bun
+```sh
+$ bun add @sentry/bun
 ```
 
 ---

docs/guides/http/hot.md

@@ -5,18 +5,22 @@ name: Hot reload an HTTP server
 Bun supports the [`--hot`](https://bun.sh/docs/runtime/hot#hot-mode) flag to run a file with hot reloading enabled. When any module or file changes, Bun re-runs the file.
 
 ```sh
-bun --hot run index.ts
+$ bun --hot run index.ts
 ```
 
 ---
 
 Bun detects when you are running an HTTP server with `Bun.serve()`. It reloads your fetch handler when source files change, _without_ restarting the `bun` process. This makes hot reloads nearly instantaneous.
 
+{% callout %}
+Note that this doesn't reload the page on your browser.
+{% /callout %}
+
 ```ts
 Bun.serve({
   port: 3000,
   fetch(req) {
-    return new Response(`Hello world`);
+    return new Response("Hello world");
   },
 });
 ```

docs/guides/install/add-peer.md

@@ -2,16 +2,43 @@
 name: Add a peer dependency
 ---
 
-To add an npm package as a peer dependency, directly modify the `peerDependencies` object in your package.json. Running `bun install` will install peer dependencies by default, unless marked optional in `peerDependenciesMeta`.
+
+To add an npm package as a peer dependency, use the `--peer` flag.
+
+```sh
+$ bun add @types/bun --peer
+```
+
+---
+
+This will add the package to `peerDependencies` in `package.json`.
 
 ```json-diff
 {
   "peerDependencies": {
-+   "zod": "^3.0.0"
++   "@types/bun": "^1.0.0"
   }
 }
 ```
 
 ---
 
+Running `bun install` will install peer dependencies by default, unless marked optional in `peerDependenciesMeta`.
+
+```json-diff
+{
+  "peerDependencies": {
+    "@types/bun": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
++   "@types/bun": {
++     "optional": true
++   }
+  }
+
+}
+```
+
+---
+
 See [Docs > Package manager](https://bun.sh/docs/cli/install) for complete documentation of Bun's package manager.

docs/guides/install/add.md

@@ -22,7 +22,7 @@ This will add the package to `dependencies` in `package.json`. By default, the `
 
 ---
 
-To "pin" to the `latest` version of the package, use `--exact`. This will add the package to `dependencies` without the `^`, pinning your project to the exact version you installed.
+To "pin" to an exact version of the package, use `--exact`. This will add the package to `dependencies` without the `^`, pinning your project to the exact version you installed.
 
 ```sh
 $ bun add zod --exact

docs/guides/install/cicd.md

@@ -13,7 +13,7 @@ jobs:
     steps:
       # ...
       - uses: actions/checkout@v4
-+     - uses: oven-sh/setup-bun@v1
++     - uses: oven-sh/setup-bun@v2
 
       # run any `bun` or `bunx` command
 +     - run: bun install
@@ -31,9 +31,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       # ...
-      - uses: oven-sh/setup-bun@v1
+      - uses: oven-sh/setup-bun@v2
 +       with:
-+         version: 0.7.0 # or "canary"
++         version: "latest" # or "canary"
 ```
 
 ---

docs/guides/install/git-diff-bun-lockfile.md

@@ -2,6 +2,12 @@
 name: Configure git to diff Bun's lockb lockfile
 ---
 
+{% callout %}
+Bun v1.1.39 introduced `bun.lock`, a JSONC formatted lockfile. `bun.lock` is human-readable and git-diffable without configuration, at no cost to performance. [**Learn more.**](https://bun.sh/docs/install/lockfile#text-based-lockfile)
+{% /callout %}
+
+---
+
 To teach `git` how to generate a human-readable diff of Bun's binary lockfile format (`.lockb`), add the following to your local or global `.gitattributes` file:
 
 ```js

docs/guides/install/trusted.md

@@ -23,8 +23,6 @@ To allow Bun to execute lifecycle scripts for a specific package, add the packag
 Note that this only allows lifecycle scripts for the specific package listed in `trustedDependencies`, _not_ the dependencies of that dependency!
 {% /callout %}
 
-<!-- Bun maintains an allow-list of popular packages containing `postinstall` scripts that are known to be safe. To run lifecycle scripts for packages that aren't on this list, add the package to `trustedDependencies` in your package.json. -->
-
 ```json-diff
   {
     "name": "my-app",

docs/guides/install/yarnlock.md

@@ -2,6 +2,12 @@
 name: Generate a human-readable lockfile
 ---
 
+{% callout %}
+Bun v1.1.39 introduced `bun.lock`, a JSONC formatted lockfile. `bun.lock` is human-readable and git-diffable without configuration, at no cost to performance. [**Learn more.**](https://bun.sh/docs/install/lockfile#text-based-lockfile)
+{% /callout %}
+
+---
+
 By default Bun generates a binary `bun.lockb` file when you run `bun install`. In some cases, it's preferable to generate a human-readable lockfile instead.
 
 ---

docs/guides/process/argv.md

@@ -44,9 +44,11 @@ console.log(values);
 console.log(positionals);
 ```
 
+---
+
 then it outputs
 
-```
+```sh
 $ bun run cli.ts --flag1 --flag2 value
 {
   flag1: true,

docs/guides/runtime/define-constant.md

@@ -4,9 +4,9 @@ name: Define and replace static globals & constants
 
 The `--define` flag lets you declare statically-analyzable constants and globals. It replace all usages of an identifier or property in a JavaScript or TypeScript file with a constant value. This feature is supported at runtime and also in `bun build`. This is sort of similar to `#define` in C/C++, except for JavaScript.
 
-```ts
-bun --define process.env.NODE_ENV="'production'" src/index.ts # Runtime
-bun build --define process.env.NODE_ENV="'production'" src/index.ts # Build
+```sh
+$ bun --define process.env.NODE_ENV="'production'" src/index.ts # Runtime
+$ bun build --define process.env.NODE_ENV="'production'" src/index.ts # Build
 ```
 
 ---
@@ -25,12 +25,12 @@ if (process.env.NODE_ENV === "production") {
 
 Before the code reaches the JavaScript engine, Bun replaces `process.env.NODE_ENV` with `"production"`.
 
-```ts
-if ("production" === "production") {
-  console.log("Production mode");
-} else {
-  console.log("Development mode");
-}
+```ts-diff
++ if ("production" === "production") {
+    console.log("Production mode");
+  } else {
+    console.log("Development mode");
+  }
 ```
 
 ---
@@ -39,12 +39,12 @@ It doesn't stop there. Bun's optimizing transpiler is smart enough to do some ba
 
 Since `"production" === "production"` is always `true`, Bun replaces the entire expression with the `true` value.
 
-```ts
-if (true) {
-  console.log("Production mode");
-} else {
-  console.log("Development mode");
-}
+```ts-diff
++ if (true) {
+    console.log("Production mode");
+  } else {
+    console.log("Development mode");
+  }
 ```
 
 ---

docs/guides/write-file/unlink.md

@@ -2,10 +2,15 @@
 name: Delete a file
 ---
 
-To delete a file in Bun, use the `delete` method.
+The `Bun.file()` function accepts a path and returns a `BunFile` instance. Use the `.delete()` method to delete the file.
 
 ```ts
-import { file } from "bun";
+const path = "/path/to/file.txt";
+const file = Bun.file(path);
 
-await file("./path-to-file.txt").delete();
+await file.delete();
 ```
+
+---
+
+See [Docs > API > File I/O](https://bun.sh/docs/api/file-io#reading-files-bun-file) for complete documentation of `Bun.file()`.

docs/install/cache.md

@@ -15,6 +15,8 @@ disable = false
 disableManifest = false
 ```
 
+{% /details %}
+
 ## Minimizing re-downloads
 
 Bun strives to avoid re-downloading packages multiple times. When installing a package, if the cache already contains a version in the range specified by `package.json`, Bun will use the cached package instead of downloading it again.
@@ -33,14 +35,14 @@ Once a package is downloaded into the cache, Bun still needs to copy those files
 
 ## Saving disk space
 
-Since Bun uses hardlinks to "copy" a module into a project's `node_modules` directory on Linux, the contents of the package only exist in a single location on disk, greatly reducing the amount of disk space dedicated to `node_modules`.
+Since Bun uses hardlinks to "copy" a module into a project's `node_modules` directory on Linux and Windows, the contents of the package only exist in a single location on disk, greatly reducing the amount of disk space dedicated to `node_modules`.
 
 This benefit also applies to macOS, but there are exceptions. It uses `clonefile` which is copy-on-write, meaning it will not occupy disk space, but it will count towards drive's limit. This behavior is useful if something attempts to patch `node_modules/*`, so it's impossible to affect other installations.
 
 {% details summary="Installation strategies" %}
 This behavior is configurable with the `--backend` flag, which is respected by all of Bun's package management commands.
 
-- **`hardlink`**: Default on Linux.
+- **`hardlink`**: Default on Linux and Windows.
 - **`clonefile`** Default on macOS.
 - **`clonefile_each_dir`**: Similar to `clonefile`, except it clones each file individually per directory. It is only available on macOS and tends to perform slower than `clonefile`.
 - **`copyfile`**: The fallback used when any of the above fail. It is the slowest option. On macOS, it uses `fcopyfile()`; on Linux it uses `copy_file_range()`.

docs/install/lockfile.md

@@ -59,7 +59,7 @@ $ bun install --lockfile-only
 
 {% callout %}
 **Note** - using `--lockfile-only` will still populate the global install cache with registry metadata and git/tarball dependencies.
-{% endcallout %}
+{% /callout %}
 
 #### Can I opt out?
 

docs/runtime/env.md

@@ -30,9 +30,9 @@ process.env.FOO = "hello";
 Bun supports `--env-file` to override which specific `.env` file to load. You can use `--env-file` when running scripts in bun's runtime, or when running package.json scripts.
 
 ```sh
-bun --env-file=.env.1 src/index.ts
+$ bun --env-file=.env.1 src/index.ts
 
-bun --env-file=.env.abc --env-file=.env.def run build
+$ bun --env-file=.env.abc --env-file=.env.def run build
 ```
 
 ### Quotation marks