diff options
Diffstat (limited to 'docs/cli/install.md')
| -rw-r--r-- | docs/cli/install.md | 285 |
1 files changed, 72 insertions, 213 deletions
diff --git a/docs/cli/install.md b/docs/cli/install.md index 3a60fb054..63dbb1163 100644 --- a/docs/cli/install.md +++ b/docs/cli/install.md @@ -23,41 +23,19 @@ sudo apt install --install-recommends linux-generic-hwe-20.04 {% /details %} -## `bun install` - To install all dependencies of a project: ```bash $ bun install ``` -On Linux, `bun install` tends to install packages 20-100x faster than `npm install`. On macOS, it's more like 4-80x. - - - Running `bun install` will: - **Install** all `dependencies`, `devDependencies`, and `optionalDependencies`. Bun does not install `peerDependencies` by default. - **Run** your project's `{pre|post}install` and `{pre|post}prepare` scripts at the appropriate time. For security reasons Bun _does not execute_ lifecycle scripts of installed dependencies. - **Write** a `bun.lockb` lockfile to the project root. -To install in production mode (i.e. without `devDependencies` or `optionalDependencies`): - -```bash -$ bun install --production -``` - -To install with reproducible dependencies, use `--frozen-lockfile`. If your `package.json` disagrees with `bun.lockb`, Bun will exit with an error. This is useful for production builds and CI environments. - -```bash -$ bun install --frozen-lockfile -``` - -To perform a dry run (i.e. don't actually install anything): - -```bash -$ bun install --dry-run -``` +## Logging To modify logging verbosity: @@ -66,99 +44,59 @@ $ bun install --verbose # debug logging $ bun install --silent # no logging ``` -{% details summary="Configuring behavior" %} -The default behavior of `bun install` can be configured in `bunfig.toml`: - -```toml -[install] - -# whether to install optionalDependencies -optional = true - -# whether to install devDependencies -dev = true - -# whether to install peerDependencies -peer = false - -# equivalent to `--production` flag -production = false - -# equivalent to `--frozen-lockfile` flag -frozenLockfile = false - -# equivalent to `--dry-run` flag -dryRun = false -``` - -{% /details %} - -## `bun add` - -To add a particular package: - -```bash -$ bun add preact -``` +## Lifecycle scripts -To specify a version, version range, or tag: +Unlike other npm clients, Bun does not execute arbitrary lifecycle scripts like `postinstall` for installed dependencies. Executing arbitrary scripts represents a potential security risk. -```bash -$ bun add zod@3.20.0 -$ bun add zod@^3.0.0 -$ bun add zod@latest -``` - -To add a package as a dev dependency (`"devDependencies"`): - -```bash -$ bun add --dev @types/react -$ bun add -d @types/react -``` - -To add a package as an optional dependency (`"optionalDependencies"`): +To tell Bun to allow lifecycle scripts for a particular package, add the package to `trustedDependencies` in your package.json. -```bash -$ bun add --optional lodash +```json-diff + { + "name": "my-app", + "version": "1.0.0", ++ "trustedDependencies": ["my-trusted-package"] + } ``` -To add a package and pin to the resolved version, use `--exact`. This will resolve the version of the package and add it to your `package.json` with an exact version number instead of a version range. +Then re-install the package. Bun will read this field and run lifecycle scripts for `my-trusted-package`. -```bash -$ bun add react --exact -``` +## Workspaces -This will add the following to your `package.json`: +Bun supports `"workspaces"` in package.json. For complete documentation refer to [Package manager > Workspaces](/docs/install/workspaces). -```jsonc +```json#package.json { + "name": "my-app", + "version": "1.0.0", + "workspaces": ["packages/*"], "dependencies": { - // without --exact - "react": "^18.2.0", // this matches >= 18.2.0 < 19.0.0 - - // with --exact - "react": "18.2.0" // this matches only 18.2.0 exactly + "preact": "^10.5.13" } } ``` -To view a complete list of options for this command: +## Overrides and resolutions -```bash -$ bun add --help -``` +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-and-resolutions) for complete documentation. -## `bun add --global` +```json-diff#package.json + { + "name": "my-app", + "dependencies": { + "foo": "^2.0.0" + }, ++ "overrides": { ++ "bar": "~4.4.0" ++ } + } +``` -{% callout %} -**Note** — This would not modify package.json of your current project folder. -**Alias** - `bun add --global`, `bun add -g`, `bun install --global` and `bun install -g` -{% /callout %} +## Global packages -To install a package globally, use the `-g`/`--global` flag. This will not modify the `package.json` of your current project. Typically this is used for installing command-line tools. +To install a package globally, use the `-g`/`--global` flag. Typically this is used for installing command-line tools. ```bash -$ bun add --global cowsay # or `bun add -g cowsay` +$ bun install --global cowsay # or `bun install -g cowsay` $ cowsay "Bun!" ______ < Bun! > @@ -170,154 +108,75 @@ $ cowsay "Bun!" || || ``` -{% details summary="Configuring global installation behavior" %} - -```toml -[install] -# where `bun install --global` installs packages -globalDir = "~/.bun/install/global" - -# where globally-installed package bins are linked -globalBinDir = "~/.bun/bin" -``` +## Production mode -{% /details %} - -## `bun remove` - -To remove a dependency: - -```bash -$ bun remove preact -``` - -## `bun update` - -To update all dependencies to the latest version _that's compatible with the version range specified in your `package.json`_: - -```sh -$ bun update -``` - -This will not edit your `package.json`. There's currently no command to force-update all dependencies to the latest version regardless version ranges. - -## `bun link` - -Use `bun link` in a local directory to register the current package as a "linkable" package. +To install in production mode (i.e. without `devDependencies` or `optionalDependencies`): ```bash -$ cd /path/to/cool-pkg -$ cat package.json -{ - "name": "cool-pkg", - "version": "1.0.0" -} -$ bun link -bun link v1.x (7416672e) -Success! Registered "cool-pkg" - -To use cool-pkg in a project, run: - bun link cool-pkg - -Or add it in dependencies in your package.json file: - "cool-pkg": "link:cool-pkg" +$ bun install --production ``` -This package can now be "linked" into other projects using `bun link cool-pkg`. This will create a symlink in the `node_modules` directory of the target project, pointing to the local directory. +For reproducible installs, use `--frozen-lockfile`. This will install the exact versions of each package specified in the lockfile. If your `package.json` disagrees with `bun.lockb`, Bun will exit with an error. The lockfile will not be updated. ```bash -$ cd /path/to/my-app -$ bun link cool-pkg -``` - -In addition, the `--save` flag can be used to add `cool-pkg` to the `dependencies` field of your app's package.json with a special version specifier that tells Bun to load from the registered local directory instead of installing from `npm`: - -```json-diff - { - "name": "my-app", - "version": "1.0.0", - "dependencies": { -+ "cool-pkg": "link:cool-pkg" - } - } -``` - -## Trusted dependencies - -Unlike other npm clients, Bun does not execute arbitrary lifecycle scripts for installed dependencies, such as `postinstall`. These scripts represent a potential security risk, as they can execute arbitrary code on your machine. - -<!-- 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. --> - -To tell Bun to allow lifecycle scripts for a particular package, add the package to `trustedDependencies` in your package.json. - -<!-- ```json-diff - { - "name": "my-app", - "version": "1.0.0", -+ "trustedDependencies": { -+ "my-trusted-package": "*" -+ } - } -``` --> - -```json-diff - { - "name": "my-app", - "version": "1.0.0", -+ "trustedDependencies": ["my-trusted-package"] - } +$ bun install --frozen-lockfile ``` -Bun reads this field and will run lifecycle scripts for `my-trusted-package`. +For more information on Bun's binary lockfile `bun.lockb`, refer to [Package manager > Lockfile](/docs/install/lockfile). -<!-- If you specify a version range, Bun will only execute lifecycle scripts if the resolved package version matches the range. --> -<!-- -```json -{ - "name": "my-app", - "version": "1.0.0", - "trustedDependencies": { - "my-trusted-package": "^1.0.0" - } -} -``` --> +## Dry run -## Git dependencies - -To add a dependency from a git repository: +To perform a dry run (i.e. don't actually install anything): ```bash -$ bun install git@github.com:moment/moment.git +$ bun install --dry-run ``` -Bun supports a variety of protocols, including [`github`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#github-urls), [`git`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#git-urls-as-dependencies), `git+ssh`, `git+https`, and many more. +## Non-npm dependencies -```json +Bun supports installing dependencies from Git, GitHub, and local or remotely-hosted tarballs. For complete documentation refer to [Package manager > Git, GitHub, and tarball dependencies](/docs/cli/add). + +```json#package.json { "dependencies": { "dayjs": "git+https://github.com/iamkun/dayjs.git", "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21", "moment": "git@github.com:moment/moment.git", - "zod": "github:colinhacks/zod" + "zod": "github:colinhacks/zod", + "react": "https://registry.npmjs.org/react/-/react-18.2.0.tgz" } } ``` -## Tarball dependencies +## Configuration -A package name can correspond to a publicly hosted `.tgz` file. During `bun install`, Bun will download and install the package from the specified tarball URL, rather than from the package registry. +The default behavior of `bun install` can be configured in `bunfig.toml`. The default values are shown below. -```json#package.json -{ - "dependencies": { - "zod": "https://registry.npmjs.org/zod/-/zod-3.21.4.tgz" - } -} +```toml +[install] + +# whether to install optionalDependencies +optional = true + +# whether to install devDependencies +dev = true + +# whether to install peerDependencies +peer = false + +# equivalent to `--production` flag +production = false + +# equivalent to `--frozen-lockfile` flag +frozenLockfile = false + +# equivalent to `--dry-run` flag +dryRun = false ``` ## CI/CD -Looking to speed up your CI? Use the official `oven-sh/setup-bun` action to install `bun` in a GitHub Actions pipeline. +Looking to speed up your CI? Use the official [`oven-sh/setup-bun`](https://github.com/oven-sh/setup-bun) action to install `bun` in a GitHub Actions pipeline. ```yaml#.github/workflows/release.yml name: bun-types |