From aff2da47604db9aa513f5a9d410ca9d50917f2a4 Mon Sep 17 00:00:00 2001 From: robobun <117481402+robobun@users.noreply.github.com> Date: Sat, 15 Aug 2026 02:25:22 +0000 Subject: [PATCH 1/2] docs(pm): describe when bun update rewrites catalog entries A plain bun update (with or without --latest, -r, or a --filter that selects the root) rewrites the root catalog entries. Once the update is narrowed with package names, patterns, or --dev/--prod/--no-optional, the entries stay as written and only bun.lock moves within their ranges. The update page claimed the entries were rewritten unconditionally. --- docs/pm/catalogs.mdx | 2 ++ docs/pm/cli/update.mdx | 11 +++++++---- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/pm/catalogs.mdx b/docs/pm/catalogs.mdx index 6bd61b92428f..acb1f452c665 100644 --- a/docs/pm/catalogs.mdx +++ b/docs/pm/catalogs.mdx @@ -238,6 +238,8 @@ To update versions across all packages, change the version in the root package.j Then run `bun install` to update all packages. +[`bun update`](/pm/cli/update) with no arguments also rewrites the catalog entries, and `bun update --latest` moves them past their ranges. `bun update ` leaves catalog entries as written. To pick individual entries, use `bun update -i -r`. + ## Adding to the catalog with `bun add` `bun add --catalog` (or `--catalog=`) adds the entry to the root catalog and writes `"catalog:"` to the current package. Bun reuses an existing catalog entry unless you pass an explicit version. See [`bun add --catalog`](/pm/cli/add#--catalog). diff --git a/docs/pm/cli/update.mdx b/docs/pm/cli/update.mdx index 169b8b4e8d6d..e1509781fd20 100644 --- a/docs/pm/cli/update.mdx +++ b/docs/pm/cli/update.mdx @@ -30,7 +30,8 @@ Updated packages appear in the install summary as `↑ name old → new`, with ` - `^1.1.0` → `^1.2.0`, `~1.1.0` → `~1.1.5`. Bun preserves the operator. With [`install.exact`](/runtime/bunfig#install-exact) or `--exact`, Bun writes an exact version instead. - Exact pins, dist-tags (`"latest"`, `"next"`), and other range forms (`*`, `1.x`, `>=1.0.0`) are left as written; only `bun.lock` moves. `--latest` rewrites them. -- Bun never rewrites `catalog:` references; it updates the catalog entry in the root `package.json` instead. +- Bun never rewrites `catalog:` references. A plain `bun update` also rewrites the [catalog](/pm/catalogs) entries in the root `package.json` by the rules above, even when you run it inside a workspace package. `--latest` moves them past their ranges. +- Once you narrow the update, with package names, patterns, `--dev`, `--prod`, or `--no-optional`, Bun leaves catalog entries as written. The packages behind them still move in `bun.lock` within the entry's range, and `--latest` does not apply to them. To move one catalog entry past its range, select it in [`bun update -i -r --latest`](#--interactive), or edit the entry and run `bun install`. - `--no-save` updates `node_modules` only, leaving `package.json` and `bun.lock` untouched. ### What is held back @@ -50,6 +51,8 @@ bun update -i `--interactive` opens a terminal interface listing every outdated direct dependency. Bun updates the packages you select as if you had run `bun update ...`; everything else keeps its locked version. +The list includes dependencies a workspace takes from a [catalog](/pm/catalogs). Selecting one rewrites the catalog entry in the root `package.json`. From the root of a monorepo, pass `-r` so that the workspaces using the catalog are included. + ### Interactive Interface The interface displays packages grouped by dependency type: @@ -121,10 +124,10 @@ Within each section, individual packages may have a suffix (` dev`, ` peer`, ` o ## `--recursive` and `--filter` -In a monorepo, `bun update` only rewrites the `package.json` of the workspace you run it in. From the root, it still updates the transitive dependencies of every workspace in `bun.lock`. +In a monorepo, `bun update` only rewrites the `package.json` of the workspace you run it in. A plain run also rewrites the root's catalog entries. From the root, `bun update` still updates the transitive dependencies of every workspace in `bun.lock`. - `--recursive` (`-r`) updates every workspace's `package.json`. -- `--filter ` (`-F`) updates only the matching workspaces, using the [filter syntax](/pm/filter). As with `bun install --filter`, Bun links only the selected workspaces afterwards. +- `--filter ` (`-F`) updates only the matching workspaces, using the [filter syntax](/pm/filter). Bun rewrites catalog entries only when the root is among the selected workspaces. As with `bun install --filter`, Bun links only the selected workspaces afterwards. Both combine with package names, `--latest`, `--dry-run`, and `--interactive` (which adds a "Workspace" column). @@ -168,7 +171,7 @@ bun update -g typescript By default, `bun update` updates each dependency to the latest version that satisfies the version range in your `package.json`. -To update direct dependencies to the latest version regardless of the declared range, use `--latest` (`-L`). Bun rewrites the `package.json` entry to a range of the same style on the new version. Transitive dependencies still respect the ranges their dependents declare. Bun does not downgrade a dependency that is already ahead of `latest` (e.g. a prerelease). +To update direct dependencies to the latest version regardless of the declared range, use `--latest` (`-L`). Bun rewrites the `package.json` entry to a range of the same style on the new version. A plain `bun update --latest` also moves catalog entries past their ranges. Once you narrow the update to particular packages, Bun leaves catalog entries as written. Transitive dependencies still respect the ranges their dependents declare. Bun does not downgrade a dependency that is already ahead of `latest` (e.g. a prerelease). ```sh terminal icon="terminal" bun update --latest From 09ce75e74d7247138cb4d0424e9e03cfa3407007 Mon Sep 17 00:00:00 2001 From: robobun <117481402+robobun@users.noreply.github.com> Date: Sat, 15 Aug 2026 02:32:25 +0000 Subject: [PATCH 2/2] docs(pm): say that --latest follows the same catalog scope rule on the catalogs page --- docs/pm/catalogs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pm/catalogs.mdx b/docs/pm/catalogs.mdx index acb1f452c665..cb58628ed2e8 100644 --- a/docs/pm/catalogs.mdx +++ b/docs/pm/catalogs.mdx @@ -238,7 +238,7 @@ To update versions across all packages, change the version in the root package.j Then run `bun install` to update all packages. -[`bun update`](/pm/cli/update) with no arguments also rewrites the catalog entries, and `bun update --latest` moves them past their ranges. `bun update ` leaves catalog entries as written. To pick individual entries, use `bun update -i -r`. +[`bun update`](/pm/cli/update) with no arguments also rewrites the catalog entries. `bun update --latest`, still with no package names, moves them past their ranges. `bun update ` leaves catalog entries as written, with or without `--latest`. To pick individual entries, use `bun update -i -r`; add `--latest` to also offer versions outside the current ranges. ## Adding to the catalog with `bun add`