From 2bc70df266d2216efde264cbea9aa8addf7ddeef Mon Sep 17 00:00:00 2001 From: Michael H Date: Sat, 11 Jan 2025 17:38:41 +1100 Subject: [PATCH] minor guide fixes for consistency (#16273) --- docs/api/file-io.md | 8 +++++ docs/cli/install.md | 6 ++-- docs/guides/ecosystem/discordjs.md | 14 ++++----- docs/guides/ecosystem/hono.md | 4 +-- docs/guides/ecosystem/mongoose.md | 12 ++++---- docs/guides/ecosystem/nextjs.md | 2 ++ docs/guides/ecosystem/render.md | 18 ++++++------ docs/guides/ecosystem/sentry.md | 4 +-- docs/guides/http/hot.md | 8 +++-- docs/guides/install/add-peer.md | 31 ++++++++++++++++++-- docs/guides/install/add.md | 2 +- docs/guides/install/cicd.md | 6 ++-- docs/guides/install/git-diff-bun-lockfile.md | 6 ++++ docs/guides/install/trusted.md | 2 -- docs/guides/install/yarnlock.md | 6 ++++ docs/guides/process/argv.md | 4 ++- docs/guides/runtime/define-constant.md | 30 +++++++++---------- docs/guides/write-file/unlink.md | 11 +++++-- docs/install/cache.md | 6 ++-- docs/install/lockfile.md | 2 +- docs/runtime/env.md | 4 +-- 21 files changed, 123 insertions(+), 63 deletions(-) diff --git a/docs/api/file-io.md b/docs/api/file-io.md index f9fd2368f37e2d..1f8e9468bf5a66 100644 --- a/docs/api/file-io.md +++ b/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` diff --git a/docs/cli/install.md b/docs/cli/install.md index 060031a35b17e2..bc7a12fdfa8b4e 100644 --- a/docs/cli/install.md +++ b/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 diff --git a/docs/guides/ecosystem/discordjs.md b/docs/guides/ecosystem/discordjs.md index ec12a247d946fe..db13548e35349d 100644 --- a/docs/guides/ecosystem/discordjs.md +++ b/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 ``` diff --git a/docs/guides/ecosystem/hono.md b/docs/guides/ecosystem/hono.md index df662973d40ff6..fe067a18402d87 100644 --- a/docs/guides/ecosystem/hono.md +++ b/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 ``` diff --git a/docs/guides/ecosystem/mongoose.md b/docs/guides/ecosystem/mongoose.md index c06821ddea4224..0a6d2e24e0bc96 100644 --- a/docs/guides/ecosystem/mongoose.md +++ b/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 ``` --- diff --git a/docs/guides/ecosystem/nextjs.md b/docs/guides/ecosystem/nextjs.md index 1183b430e07c0c..e54a7bca619271 100644 --- a/docs/guides/ecosystem/nextjs.md +++ b/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 diff --git a/docs/guides/ecosystem/render.md b/docs/guides/ecosystem/render.md index cad2792b122bb0..4fa4a887b7ca6f 100644 --- a/docs/guides/ecosystem/render.md +++ b/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 ``` --- diff --git a/docs/guides/ecosystem/sentry.md b/docs/guides/ecosystem/sentry.md index 77714ad9eea9bd..a513720ed5b0fd 100644 --- a/docs/guides/ecosystem/sentry.md +++ b/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 ``` --- diff --git a/docs/guides/http/hot.md b/docs/guides/http/hot.md index 794c1033f13b1d..ecb1b2ed90e9cb 100644 --- a/docs/guides/http/hot.md +++ b/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"); }, }); ``` diff --git a/docs/guides/install/add-peer.md b/docs/guides/install/add-peer.md index beb3fb10af5394..059be163a85338 100644 --- a/docs/guides/install/add-peer.md +++ b/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. diff --git a/docs/guides/install/add.md b/docs/guides/install/add.md index c7288455052ab9..2406ca375aa415 100644 --- a/docs/guides/install/add.md +++ b/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 diff --git a/docs/guides/install/cicd.md b/docs/guides/install/cicd.md index 2e5b6df3ce9782..1e5b60b7117688 100644 --- a/docs/guides/install/cicd.md +++ b/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" ``` --- diff --git a/docs/guides/install/git-diff-bun-lockfile.md b/docs/guides/install/git-diff-bun-lockfile.md index cf1cfc4cd99be2..27bb181e5e3651 100644 --- a/docs/guides/install/git-diff-bun-lockfile.md +++ b/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 diff --git a/docs/guides/install/trusted.md b/docs/guides/install/trusted.md index 75c6cfbd2258da..8e51c57f365857 100644 --- a/docs/guides/install/trusted.md +++ b/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 %} - - ```json-diff { "name": "my-app", diff --git a/docs/guides/install/yarnlock.md b/docs/guides/install/yarnlock.md index 93c12b404646ba..d5383de64bfe0c 100644 --- a/docs/guides/install/yarnlock.md +++ b/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. --- diff --git a/docs/guides/process/argv.md b/docs/guides/process/argv.md index 3acb68e52f7268..88398a64719131 100644 --- a/docs/guides/process/argv.md +++ b/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, diff --git a/docs/guides/runtime/define-constant.md b/docs/guides/runtime/define-constant.md index 7c599a759070d9..8915dc45017bf9 100644 --- a/docs/guides/runtime/define-constant.md +++ b/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"); + } ``` --- diff --git a/docs/guides/write-file/unlink.md b/docs/guides/write-file/unlink.md index ef2fc5fb2c92e8..84cff374f3c6b6 100644 --- a/docs/guides/write-file/unlink.md +++ b/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()`. diff --git a/docs/install/cache.md b/docs/install/cache.md index f03f75e432bfff..f1e84d4ceaaaaa 100644 --- a/docs/install/cache.md +++ b/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()`. diff --git a/docs/install/lockfile.md b/docs/install/lockfile.md index 88b858bd5361f6..533bc6489ca32f 100644 --- a/docs/install/lockfile.md +++ b/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? diff --git a/docs/runtime/env.md b/docs/runtime/env.md index 54cda70d3d8661..ca0804818f7105 100644 --- a/docs/runtime/env.md +++ b/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