Add ecosystem guides (#3847)

* Add ecosystem guides

* Update titles

* Rename stric

* Add unlink and fetch guides

* Add formdata guide

* Tweak title

* Moar

11 files changed, 309 insertions, 0 deletions

diff --git a/docs/guides/install/add-dev.md b/docs/guides/install/add-dev.md
new file mode 100644
index 000000000..833f8cfa2
--- /dev/null
+++ b/docs/guides/install/add-dev.md
@@ -0,0 +1,26 @@
+---
+name: Add a development dependency
+---
+
+To add an npm package as a development dependency, use `bun add --development`.
+
+```sh
+$ bun add zod --development
+$ bun add zod -d # shorthand
+```
+
+---
+
+This will add the package to `devDependencies` in `package.json`.
+
+```json-diff
+{
+  "devDependencies": {
++   "zod": "^3.0.0"
+  }
+}
+```
+
+---
+
+See [Docs > Package manager](/docs/cli/install) for complete documentation of Bun's package manager.
diff --git a/docs/guides/install/add-git.md b/docs/guides/install/add-git.md
new file mode 100644
index 000000000..c98bc29a8
--- /dev/null
+++ b/docs/guides/install/add-git.md
@@ -0,0 +1,36 @@
+---
+name: Add a Git dependency
+---
+
+Bun supports directly adding GitHub repositories as dependencies of your project.
+
+```sh
+$ bun add github:lodash/lodash
+```
+
+---
+
+This will add the following line to your `package.json`:
+
+```json-diff#package.json
+{
+  "dependencies": {
++   "lodash": "github:lodash/lodash"
+  }
+}
+```
+
+---
+
+Bun supports a number of protocols for specifying Git dependencies.
+
+```sh
+$ bun add git+https://github.com/lodash/lodash.git
+$ bun add git+ssh://github.com/lodash/lodash.git#4.17.21
+$ bun add git@github.com:lodash/lodash.git
+$ bun add github:colinhacks/zod
+```
+
+---
+
+See [Docs > Package manager](/docs/cli/install) for complete documentation of Bun's package manager.
diff --git a/docs/guides/install/add-optional.md b/docs/guides/install/add-optional.md
new file mode 100644
index 000000000..6d02c23e2
--- /dev/null
+++ b/docs/guides/install/add-optional.md
@@ -0,0 +1,25 @@
+---
+name: Add an optional dependency
+---
+
+To add an npm package as a peer dependency, use the `--optional` flag.
+
+```sh
+$ bun add zod --optional
+```
+
+---
+
+This will add the package to `optionalDependencies` in `package.json`.
+
+```json-diff
+{
+  "optionalDependencies": {
++   "zod": "^3.0.0"
+  }
+}
+```
+
+---
+
+See [Docs > Package manager](/docs/cli/install) for complete documentation of Bun's package manager.
diff --git a/docs/guides/install/add-peer.md b/docs/guides/install/add-peer.md
new file mode 100644
index 000000000..78d5c86b3
--- /dev/null
+++ b/docs/guides/install/add-peer.md
@@ -0,0 +1,17 @@
+---
+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 not install peer dependencies.
+
+```json-diff
+{
+  "peerDependencies": {
++   "zod": "^3.0.0"
+  }
+}
+```
+
+---
+
+See [Docs > Package manager](/docs/cli/install) for complete documentation of Bun's package manager.
diff --git a/docs/guides/install/add-tarball.md b/docs/guides/install/add-tarball.md
new file mode 100644
index 000000000..f09dbbbfa
--- /dev/null
+++ b/docs/guides/install/add-tarball.md
@@ -0,0 +1,33 @@
+---
+name: Add a tarball dependency
+---
+
+Bun's package manager can install any publicly available tarball URL as a dependency of your project.
+
+```sh
+$ bun add zod@https://registry.npmjs.org/zod/-/zod-3.21.4.tgz
+```
+
+---
+
+Running this command will download, extract, and install the tarball to your project's `node_modules` directory. It will also add the following line to your `package.json`:
+
+```json-diff#package.json
+{
+  "dependencies": {
++   "zod": "https://registry.npmjs.org/zod/-/zod-3.21.4.tgz"
+  }
+}
+```
+
+---
+
+The package `"zod"` can now be imported as usual.
+
+```ts
+import { z } from "zod";
+```
+
+---
+
+See [Docs > Package manager](/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
new file mode 100644
index 000000000..dfb88e5e4
--- /dev/null
+++ b/docs/guides/install/add.md
@@ -0,0 +1,42 @@
+---
+name: Add a dependency
+---
+
+To add an npm package as a dependency, use `bun add`.
+
+```sh
+$ bun add zod
+```
+
+---
+
+This will add the package to `dependencies` in `package.json`. By default, the `^` range specifier will be used, to indicate that any future minor or patch versions are acceptable.
+
+```json-diff
+{
+  "dependencies": {
++     "zod": "^3.0.0"
+  }
+}
+```
+
+---
+
+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.
+
+```sh
+$ bun add zod --exact
+```
+
+---
+
+To specify an exact version or a tag:
+
+```sh
+$ bun add zod@3.0.0
+$ bun add zod@next
+```
+
+---
+
+See [Docs > Package manager](/docs/cli/install) for complete documentation of Bun's package manager.
diff --git a/docs/guides/install/cicd.md b/docs/guides/install/cicd.md
new file mode 100644
index 000000000..4be29925d
--- /dev/null
+++ b/docs/guides/install/cicd.md
@@ -0,0 +1,41 @@
+---
+name: Install dependencies with Bun in GitHub Actions
+---
+
+Use the official [`setup-bun`](https://github.com/oven-sh/setup-bun) GitHub Action to install `bun` in your GitHub Actions runner.
+
+```yaml-diff#workflow.yml
+name: my-workflow
+jobs:
+  my-job:
+    name: my-job
+    runs-on: ubuntu-latest
+    steps:
+      # ...
+      - uses: actions/checkout@v3
++     - uses: oven-sh/setup-bun@v1
+
+      # run any `bun` or `bunx` command
++     - run: bun install
+```
+
+---
+
+To specify a version of Bun to install:
+
+```yaml-diff#workflow.yml
+name: my-workflow
+jobs:
+  my-job:
+    name: my-job
+    runs-on: ubuntu-latest
+    steps:
+      # ...
+      - uses: oven-sh/setup-bun@v1
++       with:
++         version: 0.7.0 # or "canary"
+```
+
+---
+
+Refer to the [README.md](https://github.com/oven-sh/setup-bun) for complete documentation of the `setup-bun` GitHub Action.
diff --git a/docs/guides/install/custom-registry.md b/docs/guides/install/custom-registry.md
new file mode 100644
index 000000000..64b3cf76b
--- /dev/null
+++ b/docs/guides/install/custom-registry.md
@@ -0,0 +1,30 @@
+---
+name: Override the default npm registry for bun install
+---
+
+The default registry is `registry.npmjs.org`. This can be globally configured in `bunfig.toml`.
+
+```toml#bunfig.toml
+[install]
+# set default registry as a string
+registry = "https://registry.npmjs.org"
+
+# if needed, set a token
+registry = { url = "https://registry.npmjs.org", token = "123456" }
+
+# if needed, set a username/password
+registry = "https://username:password@registry.npmjs.org"
+```
+
+---
+
+Your `bunfig.toml` can reference environment variables. Bun automatically loads environment variables from `.env.local`, `.env.[NODE_ENV]`, and `.env`. See [Docs > Environment variables](/docs/cli/run#environment-variables) for more information.
+
+```toml#bunfig.toml
+[install]
+registry = { url = "https://registry.npmjs.org", token = "$npm_token" }
+```
+
+---
+
+See [Docs > Package manager](/docs/cli/install) for complete documentation of Bun's package manager.
diff --git a/docs/guides/install/index.json b/docs/guides/install/index.json
new file mode 100644
index 000000000..017ef2845
--- /dev/null
+++ b/docs/guides/install/index.json
@@ -0,0 +1,4 @@
+{
+  "name": "Package manager",
+  "description": "A collection of guides for managing dependencies with Bun's package manager"
+}
diff --git a/docs/guides/install/npm-alias.md b/docs/guides/install/npm-alias.md
new file mode 100644
index 000000000..0b38d8c71
--- /dev/null
+++ b/docs/guides/install/npm-alias.md
@@ -0,0 +1,23 @@
+---
+name: Install a package under a different name
+---
+
+To install an npm package under an alias:
+
+```sh
+$ bun add my-custom-name@npm:zod
+```
+
+---
+
+The `zod` package can now be imported as `my-custom-name`.
+
+```ts
+import { z } from "my-custom-name";
+
+z.string();
+```
+
+---
+
+See [Docs > Package manager](/docs/cli/install) for complete documentation of Bun's package manager.
diff --git a/docs/guides/install/registry-scope.md b/docs/guides/install/registry-scope.md
new file mode 100644
index 000000000..48f7dee79
--- /dev/null
+++ b/docs/guides/install/registry-scope.md
@@ -0,0 +1,32 @@
+---
+name: Configure a private registry for an organization scope with bun install
+---
+
+Bun does not read `.npmrc` files; instead private registries are configured via `bunfig.toml`. To configure a registry for a particular npm scope:
+
+```toml#bunfig.toml
+[install.scopes]
+# as a string
+"@myorg1" = "https://username:password@registry.myorg.com/"
+
+# as an object with username/password
+# you can reference environment variables
+"@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/" }
+
+```
+
+---
+
+Your `bunfig.toml` can reference environment variables. Bun automatically loads environment variables from `.env.local`, `.env.[NODE_ENV]`, and `.env`. See [Docs > Environment variables](/docs/cli/run#environment-variables) for more information.
+
+```toml#bunfig.toml
+[install.scopes]
+"@myorg3" = { token = "$npm_token", url = "https://registry.myorg.com/" }
+```
+
+---
+
+See [Docs > Package manager](/docs/cli/install) for complete documentation of Bun's package manager.