From 60d8c8ad4c805bd262e58970ab643a37eb4f68e8 Mon Sep 17 00:00:00 2001
From: Jarred Sumner <jarred@jarredsumner.com>
Date: Sun, 22 Sep 2024 00:17:41 -0700
Subject: [PATCH] Update from-npm-install-to-bun-install.md

---
 .../from-npm-install-to-bun-install.md        | 176 ++++++++++++------
 1 file changed, 124 insertions(+), 52 deletions(-)

diff --git a/docs/guides/install/from-npm-install-to-bun-install.md b/docs/guides/install/from-npm-install-to-bun-install.md
index ca3137834f6c85..07c9c8ea1b9736 100644
--- a/docs/guides/install/from-npm-install-to-bun-install.md
+++ b/docs/guides/install/from-npm-install-to-bun-install.md
@@ -2,104 +2,109 @@
 name: Migrate from npm install to bun install
 ---
 
-`bun install` is a Node.js compatible npm client designed to be an incredibly fast replacement for `npm install`.
+bun install is a Node.js compatible npm client designed to be an incredibly fast replacement for npm.
 
 We've put a lot of work into making sure that the migration path from `npm install` to `bun install` is smooth and automatic.
 
 - **Designed for Node.js & Bun**: `bun install` installs a Node.js compatible `node_modules` folder. You can use it in place of `npm install` for Node.js projects without any code changes.
-- `bun install` automatically converts `package-lock.json` to bun's `bun.lockb` lockfile format, preserving your existing resolved dependency versions without any manual work on your part
-- `bun install` reads npm registry configuration from npm's `.npmrc` as well as Bun's bunfig.toml
+- **Automatically converts `package-lock.json`** to bun's `bun.lockb` lockfile format, preserving your existing resolved dependency versions without any manual work on your part. You can secretly use `bun install` in place of `npm install` at work without anyone noticing.
+- bun install reads npm registry configuration from npm's `.npmrc` as well as Bun's bunfig.toml
 - On Windows and Linux, `bun install` uses hardlinks to conserve disk space and install times
 
-To migrate from `npm install` to `bun install`, run `bun install`:
-
 ```bash
+# It only takes one command to migrate
 $ bun i
-```
 
-## Run package.json scripts and executables with `bun run`
+# To add dependencies:
+$ bun i @types/bun
 
-To run a package.json script, you can use `bun <package.json script>`.
-
-```sh
-$ bun my-script
+# To add devDependencies:
+$ bun i -d @types/bun
 
-# This also works:
-$ bun run my-script
+# To remove a dependency:
+$ bun rm @types/bun
 ```
 
-This works for:
+---
 
-- package.json `"scripts"` (`npm run` equivalent)
-- executables in `node_modules/.bin` (`npx` equivalent, for already-installed packages)
-- JavaScript & TypeScript files (just like `node`)
+## Run package.json scripts faster
 
-If you're coming from npm, you might be used to running scripts with `npm run <script>` and packages with `npx <package>`. In Bun, we also support `bunx <package>`, but it's only needed when running executables which may not already be installed on your system or in your `node_modules/.bin`. When you use `bun run <executable>`, it will choose the locally-installed executable if you have it.
+Run scripts from package.json, executables from `node_modules/.bin` (sort of like `npx`), and JavaScript/TypeScript files (just like `node`) - all from a single simple command.
 
-### Shebang
+| NPM              | Bun              |
+| ---------------- | ---------------- |
+| `npm <script>`   | `bun <script>`   |
+| `npm exec <bin>` | `bun run <bin>`  |
+| `npx <package>`  | `bunx <package>` |
+| `node <file>`    | `bun <file>`     |
 
-Note that if the package references `node` in the `#!/usr/bin/env node` shebang, it will by default respect it and use the system's `node` executable. You can force it to use Bun's `node` by passing `--bun` to `bun run`:
+When you use `bun run <executable>`, it will choose the locally-installed executable
 
 ```sh
-$ bun --bun my-script
-```
-
-When you pass `--bun` to `bun run`, we create a symlink to the locally-installed Bun executable named `"node"` in a temporary directory and add that to your `PATH` for the duration of the script's execution.
-
-### Filter scripts by workspace name
+# Run a package.json script:
+$ bun my-script
+$ bun run my-script
 
-In Bun, the `--filter` flag accepts a glob pattern, and will run the command concurrently for all workspace packages with a `name` that matches the pattern, respecting dependency order.
+# Run an executable in node_modules/.bin:
+$ bun run my-executable # such as tsc, esbuild, etc.
 
-```sh
-# equivalent to:
-# npm run --workspace=@scope/frontend-app --workspace=@scope/frontend-design-system my-script
-bun run --filter @scope/frontend* my-script
+# Run a JavaScript/TypeScript file:
+$ bun ./index.ts
 ```
 
+---
+
 ## Workspaces
 
 `bun install` supports workspaces similarly to npm.
 
-In package.json, you can set `"workspaces"` to an array of relative paths:
+In package.json, you can set `"workspaces"` to an array of relative paths.
 
-```json
+```json#package.json
 {
   "name": "my-app",
   "workspaces": ["packages/*", "apps/*"]
-}`
+}
 ```
 
-Then, run `bun install` in the root directory:
+---
 
-```bash
-bun i
-```
+### Filter scripts by workspace name
 
-This will install the dependencies for all the workspaces, and symlink them together into the root `node_modules` folder.
+In Bun, the `--filter` flag accepts a glob pattern, and will run the command concurrently for all workspace packages with a `name` that matches the pattern, respecting dependency order.
+
+```sh
+$ bun --filter 'lib-*' my-script
+# instead of:
+# npm run --workspace lib-foo --workspace lib-bar my-script
+```
 
-We have some more information about workspaces in the [workspaces guide](/docs/install/workspaces).
+---
 
 ## Update dependencies
 
 To update a dependency, you can use `bun update <package>`. This will update the dependency to the latest version that satisfies the semver range specified in package.json.
 
 ```sh
-bun update @types/bun
-```
+# Update a single dependency
+$ bun update @types/bun
 
-If you want to update all the dependencies in your project, you can use `bun update`. This will update all the dependencies in your project to the latest versions that satisfy the semver ranges specified in package.json.
+# Update all dependencies
+$ bun update
 
-```sh
-bun update
-```
+# Ignore semver, update to the latest version
+$ bun update @types/bun --latest
 
-If you want to forcefully update a dependency to the latest version, you can use `bun update --latest <package>`. This will ignore the semver range specified in package.json and update the dependency to the latest version.
+# Update a dependency to a specific version
+$ bun update @types/bun@1.1.10
 
-```sh
-bun update @types/bun --latest
+# Update all dependencies to the latest versions
+$ bun update --latest
 ```
 
-## View outdated dependencies
+---
+
+### View outdated dependencies
 
 To view outdated dependencies, run `bun outdated`. This is like `npm outdated` but with more compact output.
 
@@ -132,10 +137,77 @@ $ bun outdated
 └────────────────────────────────────────┴─────────┴────────┴────────┘
 ```
 
+---
+
+## List installed packages
+
+To list installed packages, you can use `bun pm ls`. This will list all the packages that are installed in the `node_modules` folder using Bun's lockfile as the source of truth. You can pass the `-a` flag to list all installed packages, including transitive dependencies.
+
+```sh
+# List top-level installed packages:
+$ bun pm ls
+my-pkg node_modules (781)
+├── @types/node@20.16.5
+├── @types/react@18.3.8
+├── @types/react-dom@18.3.0
+├── eslint@8.57.1
+├── eslint-config-next@14.2.8
+
+# List all installed packages:
+$ bun pm ls -a
+my-pkg node_modules
+├── @alloc/quick-lru@5.2.0
+├── @isaacs/cliui@8.0.2
+│   └── strip-ansi@7.1.0
+│       └── ansi-regex@6.1.0
+├── @jridgewell/gen-mapping@0.3.5
+├── @jridgewell/resolve-uri@3.1.2
+...
+```
+
+---
+
 ## Create a package tarball
 
-To create a package tarball, you can use `bun pack`. This will create a tarball of the package in the current directory.
+To create a package tarball, you can use `bun pm pack`. This will create a tarball of the package in the current directory.
+
+```sh
+# Create a tarball
+$ bun pm pack
+
+Total files: 46
+Shasum: 2ee19b6f0c6b001358449ca0eadead703f326216
+Integrity: sha512-ZV0lzWTEkGAMz[...]Gl4f8lA9sl97g==
+Unpacked size: 0.41MB
+Packed size: 117.50KB
+```
+
+---
+
+## Shebang
+
+If the package references `node` in the `#!/usr/bin/env node` shebang, `bun run` will by default respect it and use the system's `node` executable. You can force it to use Bun's `node` by passing `--bun` to `bun run`.
+
+When you pass `--bun` to `bun run`, we create a symlink to the locally-installed Bun executable named `"node"` in a temporary directory and add that to your `PATH` for the duration of the script's execution.
+
+```sh
+# Force using Bun's runtime instead of node
+$ bun --bun my-script
+
+# This also works:
+$ bun run --bun my-script
+```
+
+---
+
+## Global installs
+
+You can install packages globally using `bun i -g <package>`. This will install into a `.bun/install/global/node_modules` folder inside your home directory by default.
 
 ```sh
-bun pack
+# Install a package globally
+$ bun i -g eslint
+
+# Run a globally-installed package without the `bun run` prefix
+$ eslint --init
 ```