From af8f06fd792f2c00411ed9bd84327ac4e4e76020 Mon Sep 17 00:00:00 2001
From: Luna <279187109+lunadogbot@users.noreply.github.com>
Date: Wed, 29 Apr 2026 11:42:43 +0000
Subject: [PATCH] docs: document `--package-json` flag for
 add/install/remove/uninstall (2.8)

Documents the new --package-json flag that forces dependency
management to use package.json regardless of which config file is
closer to the working directory. Adds it to install.md and add.md, and
notes that JSR packages get rewritten to their npm-compatible form
when written to package.json.

Refs denoland/deno#33199
---
 runtime/reference/cli/add.md     | 13 +++++++++++++
 runtime/reference/cli/install.md | 16 ++++++++++++++++
 2 files changed, 29 insertions(+)

diff --git a/runtime/reference/cli/add.md b/runtime/reference/cli/add.md
index 28a606e7d..f26ca6cd1 100644
--- a/runtime/reference/cli/add.md
+++ b/runtime/reference/cli/add.md
@@ -42,3 +42,16 @@ deno add --npm express
 If your project has a `package.json`, npm packages will be added to
 `dependencies` in `package.json`. Otherwise, all packages are added to the
 `imports` field in [`deno.json`](/runtime/fundamentals/configuration/).
+
+To force every dependency to be written to `package.json` (creating one if
+needed), pass `--package-json` (Deno 2.8+):
+
+```sh
+deno add --package-json npm:express jsr:@std/path
+```
+
+JSR packages added with `--package-json` are written in their npm-compatible
+form (`npm:@jsr/...`). The same flag works on
+[`deno install`](/runtime/reference/cli/install/),
+[`deno remove`](/runtime/reference/cli/remove/), and
+[`deno uninstall`](/runtime/reference/cli/uninstall/).
diff --git a/runtime/reference/cli/install.md b/runtime/reference/cli/install.md
index 517e68792..820a65015 100644
--- a/runtime/reference/cli/install.md
+++ b/runtime/reference/cli/install.md
@@ -46,6 +46,22 @@ If your project has a `package.json` file, the packages coming from npm will be
 added to `dependencies` in `package.json`. Otherwise all packages will be added
 to `deno.json`.
 
+### deno install --package-json
+
+By default, Deno picks the configuration file to write to (`deno.json` or
+`package.json`) based on which one is closest to the current working directory.
+Starting in Deno 2.8, `--package-json` forces dependencies to be written to
+`package.json`, regardless of any nearby `deno.json`. If no `package.json`
+exists yet, one is created.
+
+```sh
+deno install --package-json npm:express jsr:@std/path
+```
+
+JSR packages added with `--package-json` are written in their npm-compatible
+form (`npm:@jsr/...`). The same flag works on `deno add`, `deno remove`, and
+`deno uninstall`.
+
 ### deno install --entrypoint [FILES]
 
 Use this command to install all dependencies that are used in the provided files