diff options
Diffstat (limited to 'docs/install')
| -rw-r--r-- | docs/install/index.md | 4 | ||||
| -rw-r--r-- | docs/install/lifecycle.md | 44 | ||||
| -rw-r--r-- | docs/install/lockfile.md | 30 | ||||
| -rw-r--r-- | docs/install/overrides.md | 73 | ||||
| -rw-r--r-- | docs/install/utilities.md | 58 | ||||
| -rw-r--r-- | docs/install/workspaces.md | 51 |
6 files changed, 175 insertions, 85 deletions
diff --git a/docs/install/index.md b/docs/install/index.md index 540ade9f0..11e0d4fd4 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -69,7 +69,7 @@ $ bun install --silent # no logging ``` {% details summary="Configuring behavior" %} -The default behavior of `bun install` can be configured in `bun.toml`: +The default behavior of `bun install` can be configured in `bunfig.toml`: ```toml [install] @@ -188,7 +188,7 @@ Bun supports a variety of protocols, including [`github`](https://docs.npmjs.com ## Tarball dependencies -A package name can correspond to a publically hosted `.tgz` file. During `bun install`, Bun will download and install the package from the specified tarball URL, rather than from the package registry. +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. ```json#package.json { 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/lockfile.md b/docs/install/lockfile.md index 599403913..f8e3001ca 100644 --- a/docs/install/lockfile.md +++ b/docs/install/lockfile.md @@ -10,30 +10,24 @@ Run `bun install -y` to generate a Yarn-compatible `yarn.lock` (v1) that can be #### How do I `git diff` Bun's lockfile? -To add to the global gitattributes file: - -- First try `$XDG_CONFIG_HOME/git/attributes` -- If `$XDG_CONFIG_HOME` is not set, try `~/.config/git/attributes` - -For example, on macOS, add the following to `~/.config/git/attributes`: +Add the following to your local or global `.gitattributes` file: ``` -*.lockb diff=lockb +*.lockb binary diff=lockb ``` -Then add the following to `~/.gitconfig`: +Then add the following to you local git config with: -``` -[diff "lockb"] - textconv = bun - binary = true +```sh +$ git config diff.lockb.textconv bun +$ git config diff.lockb.binary true ``` -To only add to the local gitattributes file: +Or to your global git config (system-wide) with the `--global` option: ```sh -$ git config diff.lockb.textconv bun -$ git config diff.lockb.binary true +$ git config --global diff.lockb.textconv bun +$ git config --global diff.lockb.binary true ``` **Why this works:** @@ -85,12 +79,6 @@ print = "yarn" ```toml [install.lockfile] -# path to read bun.lockb from -path = "bun.lockb" - -# path to save bun.lockb to -savePath = "bun.lockb" - # whether to save the lockfile to disk save = true 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/install/utilities.md b/docs/install/utilities.md deleted file mode 100644 index 689f177d8..000000000 --- a/docs/install/utilities.md +++ /dev/null @@ -1,58 +0,0 @@ -The `bun pm` command group provides a set of utilities for working with Bun's package manager. - -To print the path to the `bin` directory for the local project: - -```bash -$ bun pm bin -/path/to/current/project/node_modules/.bin -``` - -To print the path to the global `bin` directory: - -```bash -$ bun pm bin -g -<$HOME>/.bun/bin -``` - -To print a list of installed dependencies in the current project and their resolved versions, excluding their dependencies. - -```bash -$ bun pm ls -/path/to/project node_modules (135) -├── eslint@8.38.0 -├── react@18.2.0 -├── react-dom@18.2.0 -├── typescript@5.0.4 -└── zod@3.21.4 -``` - -To print all installed dependencies, including nth-order dependencies. - -```bash -$ bun pm ls --all -/path/to/project node_modules (135) -├── @eslint-community/eslint-utils@4.4.0 -├── @eslint-community/regexpp@4.5.0 -├── @eslint/eslintrc@2.0.2 -├── @eslint/js@8.38.0 -├── @nodelib/fs.scandir@2.1.5 -├── @nodelib/fs.stat@2.0.5 -├── @nodelib/fs.walk@1.2.8 -├── acorn@8.8.2 -├── acorn-jsx@5.3.2 -├── ajv@6.12.6 -├── ansi-regex@5.0.1 -├── ... -``` - -To print the path to Bun's global module cache: - -```bash -$ bun pm cache -``` - -To clear Bun's global module cache: - -```bash -$ bun pm cache rm -``` diff --git a/docs/install/workspaces.md b/docs/install/workspaces.md index f2a45048a..079ef7dd4 100644 --- a/docs/install/workspaces.md +++ b/docs/install/workspaces.md @@ -1,12 +1,39 @@ Bun supports [`workspaces`](https://docs.npmjs.com/cli/v9/using-npm/workspaces?v=true#description) in `package.json`. Workspaces make it easy to develop complex software as a _monorepo_ consisting of several independent packages. -To try it, specify a list of sub-packages in the `workspaces` field of your `package.json`; it's conventional to place these sub-packages in a directory called `packages`. +It's common for a monorepo to have the following structure: + +``` +tree +<root> +├── README.md +├── bun.lockb +├── package.json +├── tsconfig.json +└── packages + ├── pkg-a + │ ├── index.ts + │ ├── package.json + │ └── tsconfig.json + ├── pkg-b + │ ├── index.ts + │ ├── package.json + │ └── tsconfig.json + └── pkg-c + ├── index.ts + ├── package.json + └── tsconfig.json +``` + +In the root `package.json`, the `"workspaces"` key is used to indicate which subdirectories should be considered packages/workspaces within the monorepo. It conventional to place all the workspace in a directory called `packages`. ```json { "name": "my-project", "version": "1.0.0", - "workspaces": ["packages/*"] + "workspaces": ["packages/*"], + "devDependencies": { + "example-package-in-monorepo": "workspace:*" + } } ``` @@ -14,9 +41,25 @@ To try it, specify a list of sub-packages in the `workspaces` field of your `pac **Glob support** — Bun supports simple `<directory>/*` globs in `"workspaces"`. Full glob syntax (e.g. `**` and `?`) is not yet supported. {% /callout %} -This has a couple major benefits. +Each workspace has it's own `package.json` When referencing other packages in the monorepo, use `"workspace:*"` as the version field in your `package.json`. + +```json +{ + "name": "pkg-a", + "version": "1.0.0", + "dependencies": { + "pkg-b": "workspace:*" + } +} +``` + +{% callout %} +**Version support** — Bun supports simple `workspace:*` versions in `"dependencies"`. Full version syntax (e.g. `workspace:^*`) is not yet supported. +{% /callout %} + +Workspaces have a couple major benefits. -- **Code can be split into logical parts.** If one package relies on another, you can simply add it as a dependency with `bun add`. If package `b` depends on `a`, `bun install` will symlink your local `packages/a` directory into the `node_modules` folder of `b`, instead of trying to download it from the npm registry. +- **Code can be split into logical parts.** If one package relies on another, you can simply add it as a dependency in `package.json`. If package `b` depends on `a`, `bun install` will install your local `packages/a` directory into `node_modules` instead of downloading it from the npm registry. - **Dependencies can be de-duplicated.** If `a` and `b` share a common dependency, it will be _hoisted_ to the root `node_modules` directory. This reduces redundant disk usage and minimizes "dependency hell" issues associated with having multiple versions of a package installed simultaneously. {% callout %} |