From 4e678627532d04e16333047987ccd099922bb987 Mon Sep 17 00:00:00 2001 From: Colin McDonnell Date: Thu, 12 Oct 2023 23:05:20 -0700 Subject: Add overrides/resolutions docs (#6476) --- docs/install/overrides.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/install/overrides.md (limited to 'docs/install/overrides.md') diff --git a/docs/install/overrides.md b/docs/install/overrides.md new file mode 100644 index 000000000..60d9e2172 --- /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-and-resolutions) 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" ++ } + } +``` -- cgit v1.2.3 From d6d4ead438c7c181e63a04c1e8afb289c21c2409 Mon Sep 17 00:00:00 2001 From: Colin McDonnell Date: Thu, 12 Oct 2023 23:08:52 -0700 Subject: Tweaks to pm docs --- docs/cli/update.md | 2 -- docs/install/overrides.md | 4 ++-- 2 files changed, 2 insertions(+), 4 deletions(-) (limited to 'docs/install/overrides.md') diff --git a/docs/cli/update.md b/docs/cli/update.md index 8ebfd6119..dfda37f01 100644 --- a/docs/cli/update.md +++ b/docs/cli/update.md @@ -1,5 +1,3 @@ -## `bun update` - To update all dependencies to the latest version _that's compatible with the version range specified in your `package.json`_: ```sh diff --git a/docs/install/overrides.md b/docs/install/overrides.md index 60d9e2172..27f5a92b2 100644 --- a/docs/install/overrides.md +++ b/docs/install/overrides.md @@ -34,7 +34,7 @@ node_modules 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"` +## `"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. @@ -54,7 +54,7 @@ Add `bar` to the `"overrides"` field in `package.json`. Bun will defer to the sp } ``` -### `"resolutions"` +## `"resolutions"` The syntax is similar for `"resolutions"`, which is Yarn's alternative to `"overrides"`. Bun supports this feature to make migration from Yarn easier. -- cgit v1.2.3 From 3f2df4526ed876869a14aaf9d373328fc4dce94e Mon Sep 17 00:00:00 2001 From: Colin McDonnell Date: Thu, 12 Oct 2023 23:17:51 -0700 Subject: Fix links --- docs/guides/install/trusted.md | 2 +- docs/install/overrides.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/install/overrides.md') diff --git a/docs/guides/install/trusted.md b/docs/guides/install/trusted.md index d0d841eea..0c1ac6362 100644 --- a/docs/guides/install/trusted.md +++ b/docs/guides/install/trusted.md @@ -47,4 +47,4 @@ Note that this only allows lifecycle scripts for the specific package listed in --- -See [Docs > Package manager > Trusted dependencies](/docs/cli/install#trusted-dependencies) for complete documentation of trusted dependencies. +See [Docs > Package manager > Trusted dependencies](/docs/install/lifecycle) for complete documentation of trusted dependencies. diff --git a/docs/install/overrides.md b/docs/install/overrides.md index 27f5a92b2..f226c35bd 100644 --- a/docs/install/overrides.md +++ b/docs/install/overrides.md @@ -1,4 +1,4 @@ -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 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 { -- cgit v1.2.3