diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/cli/pm.md (renamed from docs/install/utilities.md) | 0 | ||||
| -rw-r--r-- | docs/install/lifecycle.md | 44 | ||||
| -rw-r--r-- | docs/install/overrides.md | 73 | ||||
| -rw-r--r-- | docs/installation.md | 62 |
4 files changed, 176 insertions, 3 deletions
diff --git a/docs/install/utilities.md b/docs/cli/pm.md index 689f177d8..689f177d8 100644 --- a/docs/install/utilities.md +++ b/docs/cli/pm.md diff --git a/docs/install/lifecycle.md b/docs/install/lifecycle.md new file mode 100644 index 000000000..035ead24d --- /dev/null +++ b/docs/install/lifecycle.md @@ -0,0 +1,44 @@ +Packages on `npm` can define _lifecycle scripts_ in their `package.json`. Some of the most common are below, but there are [many others](https://docs.npmjs.com/cli/v10/using-npm/scripts). + +- `preinstall`: Runs before the package is installed +- `postinstall`: Runs after the package is installed +- `preuninstall`: Runs before the package is uninstalled +- `prepublishOnly`: Runs before the package is published + +These scripts are arbitrary shell commands that the package manager is expected to read and execute at the appropriate time. But executing arbitrary scripts represents a potential security risk, so—unlike other `npm` clients—Bun does not execute arbitrary lifecycle scripts by default. + +## `postinstall` + +The `postinstall` script is particularly important. It's widely used to build or install platform-specific binaries for packages that are implemented as [native Node.js add-ons](https://nodejs.org/api/addons.html). For example, `node-sass` is a popular package that uses `postinstall` to build a native binary for Sass. + +```json +{ + "name": "my-app", + "version": "1.0.0", + "dependencies": { + "node-sass": "^6.0.1" + } +} +``` + +## `trustedDependencies` + +Instead of executing arbitrary scripts, Bun uses a "default-secure" approach. You can add certain packages to an allow list, and Bun will execute lifecycle scripts for those packages. To tell Bun to allow lifecycle scripts for a particular package, add the package name to `trustedDependencies` array in your `package.json`. + +```json-diff + { + "name": "my-app", + "version": "1.0.0", ++ "trustedDependencies": ["node-sass"] + } +``` + +Once added to `trustedDependencies`, install/re-install the package. Bun will read this field and run lifecycle scripts for `my-trusted-package`. + +## `--ignore-scripts` + +To disable lifecycle scripts for all packages, use the `--no-scripts` flag. + +```bash +$ bun install --no-scripts +``` diff --git a/docs/install/overrides.md b/docs/install/overrides.md new file mode 100644 index 000000000..f226c35bd --- /dev/null +++ b/docs/install/overrides.md @@ -0,0 +1,73 @@ +Bun supports npm's `"overrides"` and Yarn's `"resolutions"` in `package.json`. These are mechanisms for specifying a version range for _metadependencies_—the dependencies of your dependencies. Refer to [Package manager > Overrides and resolutions](/docs/install/overrides) for complete documentation. + +```json-diff#package.json + { + "name": "my-app", + "dependencies": { + "foo": "^2.0.0" + }, ++ "overrides": { ++ "bar": "~4.4.0" ++ } + } +``` + +By default, Bun will install the latest version of all dependencies and metadependencies, according to the ranges specified in each package's `package.json`. Let's say you have a project with one dependency, `foo`, which in turn has a dependency on `bar`. This means `bar` is a _metadependency_ of our project. + +```json#package.json +{ + "name": "my-app", + "dependencies": { + "foo": "^2.0.0" + } +} +``` + +When you run `bun install`, Bun will install the latest versions of each package. + +``` +# tree layout of node_modules +node_modules +├── foo@1.2.3 +└── bar@4.5.6 +``` + +But what if a security vulnerability was introduced in `bar@4.5.6`? We may want a way to pin `bar` to an older version that doesn't have the vulerability. This is where `"overrides"`/`"resolutions"` come in. + +## `"overrides"` + +Add `bar` to the `"overrides"` field in `package.json`. Bun will defer to the specified version range when determining which version of `bar` to install, whether it's a dependency or a metadependency. + +{% callout %} +**Note** — Bun currently only supports top-level `"overrides"`. [Nested overrides](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#overrides) are not supported. +{% /callout %} + +```json-diff#package.json + { + "name": "my-app", + "dependencies": { + "foo": "^2.0.0" + }, ++ "overrides": { ++ "bar": "~4.4.0" ++ } + } +``` + +## `"resolutions"` + +The syntax is similar for `"resolutions"`, which is Yarn's alternative to `"overrides"`. Bun supports this feature to make migration from Yarn easier. + +As with `"overrides"`, _nested resolutions_ are not currently supported. + +```json-diff#package.json + { + "name": "my-app", + "dependencies": { + "foo": "^2.0.0" + }, ++ "resolutions": { ++ "bar": "~4.4.0" ++ } + } +``` diff --git a/docs/installation.md b/docs/installation.md index 73d222eaf..6aa51737a 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,9 +1,12 @@ Bun ships as a single executable that can be installed a few different ways. -## macOS and Linux +## Installing + +### macOS and Linux {% callout %} -**Linux users** — The `unzip` package is required to install Bun. Kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1. +**Linux users** — The `unzip` package is required to install Bun. Use `sudo apt install unzip` to install `unzip` package. +Kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1. Use `uname -r` to check Kernel version. {% /callout %} {% codetabs %} @@ -34,7 +37,7 @@ $ proto install bun {% /codetabs %} -## Windows +### Windows Bun provides a _limited, experimental_ native build for Windows. At the moment, only the Bun runtime is supported. @@ -66,6 +69,59 @@ $ docker pull oven/bun:alpine $ docker pull oven/bun:distroless ``` +## Checking installation + +To check that Bun was installed successfully, open a new terminal window and run `bun --version`. + +```sh +$ bun --version +1.x.y +``` + +To see the precise commit of [oven-sh/bun](https://github.com/oven-sh/bun) that you're using, run `bun --revision`. + +```sh +$ bun --revision +1.x.y+b7982ac1318937560f38e0f8eb18f45eaa43480f +``` + +If you've installed Bun but are seeing a `command not found` error, you may have to manually add the installation directory (`~/.bun/bin`) to your `PATH`. + +{% details summary="How to add to your `PATH`" %} +First, determine what shell you're using: + +```sh +$ echo $SHELL +/bin/zsh # or /bin/bash or /bin/fish +``` + +Then add these lines below to bottom of your shell's configuration file. + +{% codetabs %} + +```bash#~/.zshrc +# add to ~/.zshrc +export BUN_INSTALL="$HOME/.bun" +export PATH="$BUN_INSTALL/bin:$PATH" +``` + +```bash#~/.bashrc +# add to ~/.bashrc +export BUN_INSTALL="$HOME/.bun" +export PATH="$BUN_INSTALL/bin:$PATH" +``` + +```sh#~/.config/fish/config.fish +# add to ~/.config/fish/config.fish +export BUN_INSTALL="$HOME/.bun" +export PATH="$BUN_INSTALL/bin:$PATH" +``` + +{% /codetabs %} +Save the file. You'll need to open a new shell/terminal window for the changes to take effect. + +{% /details %} + ## Upgrading Once installed, the binary can upgrade itself. |