docs: deduplicate guide and reference content for the runtime docs (#3212)

Author: bartlomieju

README.md

@@ -134,6 +134,17 @@ files in their respective content directories.
 Static files (like screenshots) can be included directly in the `runtime`,
 `deploy`, or `kv` folders, and referenced by relative URLs in your markdown.
 
+### Guides teach, reference enumerates
+
+A topic's depth lives in exactly one place. Guide pages (like `/runtime/test/`
+or `/runtime/packages/`) teach the opinionated path with minimal flags and link
+out for detail; reference pages (under `/runtime/reference/`) enumerate every
+flag, field, and option exhaustively. Don't repeat flag or option documentation
+in a guide: link to the reference instead. A guide may include at most one
+summary table when it links to the full reference. When the same material exists
+in both kinds of page, move the depth to the reference and keep the narrative in
+the guide.
+
 ## Reference docs
 
 The reference docs served at `/api` are generated via the `deno doc` subcommand.

runtime/fundamentals/node.md

@@ -797,11 +797,13 @@ to your private registry. The `.npmrc` file must be in the project root or
 
 ```sh
 @mycompany:registry=http://mycompany.com:8111/
-//mycompany.com:8111/:_auth=secretToken
+//mycompany.com:8111/:_authToken=secretToken
 ```
 
 Replace `http://mycompany.com:8111/` with the actual URL of your private
-registry and `secretToken` with your authentication token.
+registry and `secretToken` with your authentication token. `_authToken` is the
+standard bearer-token form; registries that use legacy `_auth` credentials are
+also supported (see the `.npmrc` features list below).
 
 Then update Your `deno.json` or `package.json` to specify the import path for
 your private package. For example:

runtime/fundamentals/typescript.md

@@ -379,47 +379,3 @@ use the `compilerOptions` field in
 
 See the
 [full list of supported compiler options](/runtime/reference/ts_config_migration/#ts-compiler-options).
-
-## Using `tsconfig.json` with Deno
-
-If you're migrating a TypeScript project from Node.js, your existing
-`tsconfig.json` files work with Deno's type checker and LSP out of the box. Deno
-automatically discovers `tsconfig.json` files in directories that also contain a
-`deno.json` or `package.json`.
-
-```
-my-project/
-├── deno.json
-├── tsconfig.json       # ← discovered automatically
-├── src/
-│   └── main.ts
-└── packages/
-    └── lib/
-        ├── package.json
-        └── tsconfig.json  # ← also discovered
-```
-
-Deno supports the standard `tsconfig.json` fields: `extends`, `files`,
-`include`, `exclude`, `references`, and `compilerOptions`.
-
-:::note
-
-For Deno-first projects, prefer `compilerOptions` in `deno.json` over a separate
-`tsconfig.json`. The `tsconfig.json` compatibility exists primarily to ease
-migration of existing Node.js projects.
-
-:::
-
-### Precedence rules
-
-When both `deno.json` and `tsconfig.json` exist:
-
-1. `compilerOptions` in a parent `deno.json` take precedence over any
-   `tsconfig.json`.
-2. A `tsconfig.json` reference takes precedence over its referrer.
-3. For root references, a more deeply nested `tsconfig.json` takes precedence
-   (e.g. `foo/bar/tsconfig.json` over `foo/tsconfig.json`).
-
-For the full details on `tsconfig.json` compatibility, compiler options, and
-library configuration, see the
-[Configuring TypeScript](/runtime/reference/ts_config_migration/) reference.

runtime/getting_started/command_line_interface.md

@@ -1,7 +1,7 @@
 ---
 last_modified: 2026-05-28
 title: Command line interface
-description: "A comprehensive guide to using Deno's command-line interface (CLI). Learn about running scripts, managing permissions, using watch mode, and configuring Deno's runtime behavior through command-line flags and options."
+description: "Practical patterns for Deno's command-line interface: passing script arguments, runtime flag ordering, watch mode and its exclusions, and hot module replacement."
 oldUrl:
   - /manual/getting_started/command_line_interface
   - /runtime/manual/getting_started/command_line_interface/
@@ -16,31 +16,10 @@ standalone binaries, and a lot more. Each subcommand (`run`, `test`, `fmt`,
 `deno <subcommand> --help` to see them.
 
 For the complete list of subcommands and flags, see the
-[CLI reference](/runtime/reference/cli/). This page covers the patterns you'll
-hit early on: how to run code, how to pass arguments, and how to use watch mode.
-
-## Running scripts
-
-You can run a local TypeScript or JavaScript file by specifying its path
-relative to the current working directory:
-
-```shell
-deno run main.ts
-```
-
-Deno supports running scripts directly from URLs. This is particularly useful
-for quickly testing or running code without downloading it first:
-
-```shell
-deno run https://docs.deno.com/examples/scripts/hello_world.ts
-```
-
-You can also run a script by piping it through standard input. This is useful
-for integrating with other command-line tools or dynamically generating scripts:
-
-```shell
-cat main.ts | deno run -
-```
+[CLI reference](/runtime/reference/cli/). For the basics of running code (files,
+URLs, stdin, tasks, the permission flags), see the
+[Running code guide](/runtime/run/). This page covers the patterns that trip
+people up early: passing arguments, flag ordering, and watch mode's details.
 
 ## Passing script arguments
 

runtime/migrate/index.md

@@ -172,5 +172,3 @@ installed side by side.
   supported (`node:` built-ins, npm packages, globals) and the known gaps.
 - **[Migrating your tsconfig.json](/runtime/reference/ts_config_migration/).**
   Map `tsconfig.json` options onto `deno.json`.
-- Already on Deno and upgrading a major version? See the
-  **[Deno 1.x to 2.x migration guide](/runtime/reference/migration_guide/)**.

runtime/reference/cli/test.md

@@ -34,19 +34,32 @@ Run tests matching a glob pattern:
 deno test src/*.test.ts
 ```
 
-Run tests whose name matches a string or pattern:
+Skip type-checking:
 
 ```sh
-deno test --filter "database"
-deno test --filter "/^connect.*/"
+deno test --no-check
 ```
 
-Skip type-checking:
+## Filtering
+
+Run only the tests whose name matches a string or a pattern with `--filter`:
 
 ```sh
-deno test --no-check
+# Run tests whose name contains "database"
+deno test --filter "database"
+
+# Run tests whose name matches a regular expression
+deno test --filter "/^connect.*/"
 ```
 
+Wrap the filter value in forward slashes (`/`) to treat it as a regular
+expression, like JavaScript's regex literal syntax. Filtering does not affect
+test steps: when a test's name matches the filter, all of its steps run.
+
+To control which test files are collected in the first place, set `test.include`
+and `test.exclude` in your config file. See
+[include and exclude](/runtime/reference/deno_json/#include-and-exclude).
+
 ## Permissions
 
 Tests run with the same [permission model](/runtime/fundamentals/security/) as
@@ -103,14 +116,20 @@ deno coverage --lcov coverage/ > coverage.lcov
 
 ## Reporters
 
-Choose an output format with `--reporter`:
+Choose an output format with `--reporter`. Four reporters are built in:
+
+- `pretty` (default): detailed, human-readable output
+- `dot`: one character per test, for a concise overview
+- `junit`: JUnit XML format, for CI systems
+- `tap`: [Test Anything Protocol](https://testanything.org/) output
 
 ```sh
 deno test --reporter=dot
 deno test --reporter=tap
 ```
 
-Write a JUnit XML report for CI systems:
+Write a JUnit XML report to a file while keeping the human-readable `pretty`
+output in the terminal:
 
 ```sh
 deno test --junit-path=report.xml

runtime/reference/deno_json.md

@@ -358,9 +358,9 @@ sharing code.
 :::
 
 If you’re migrating from Node.js, your existing `tsconfig.json` files work out
-of the box with Deno. See
-[Using tsconfig.json with Deno](/runtime/fundamentals/typescript/#using-tsconfigjson-with-deno)
-for details.
+of the box with Deno. See the
+[tsconfig.json compatibility reference](/runtime/reference/ts_config_migration/)
+for the supported fields and precedence rules.
 
 For the full list of supported compiler options, library configuration, and
 advanced settings, see

runtime/reference/migration_guide.md

@@ -7,6 +7,14 @@ oldUrl:
   - /runtime/reference/migrate_deprecations/
 ---
 
+:::note Historical document
+
+This guide covers the one-time migration from Deno 1.x to Deno 2.x and is no
+longer actively updated. If you're coming to Deno from Node.js, see
+[Migrate from Node.js](/runtime/migrate/) instead.
+
+:::
+
 While we’ve accomplished a ton in Deno 1.x, the next major version is focused on
 using Deno **at scale**. This means seamless interoperability with Node.js and
 npm JavaScript infrastructure and supporting a wider range of projects and
@@ -60,15 +68,9 @@ mind. These teams work on complex codebases, sharing internal code, often using
 private registries.
 
 With Deno 2 your team can leverage private npm registries the same way you'd do
-with Node.js and npm, using an `.npmrc` file:
-
-```js title=".npmrc"
-@mycompany:registry=http://mycompany.com:8111/
-mycompany.com:8111/:_authToken=token
-```
-
-Learn more about private registry configuration
-[on `npm packages` page](/runtime/fundamentals/node/#private-registries).
+with Node.js and npm, using an `.npmrc` file. See
+[private registries](/runtime/fundamentals/node/#private-registries) for the
+configuration details.
 
 Deno 2 has workspace support, allowing you to mix Deno-first and Node-first
 packages in the same monorepo, making incremental adoption fast and

runtime/reference/ts_config_migration.md

@@ -79,6 +79,28 @@ You may be forced to use a `tsconfig.json` file when, for example, the required
 granularity for [`include`](https://www.typescriptlang.org/tsconfig/#include)
 cannot be represented with `deno.json` workspaces and directory scopes.
 
+## Migrating compilerOptions from Node.js
+
+Most of a typical Node.js `tsconfig.json` exists to configure compilation output
+and module interop. Deno runs TypeScript directly and never emits JavaScript, so
+most of those options have no effect and can be deleted. Deno warns about
+ignored options when they appear in a `tsconfig.json`; moving your remaining
+options into `deno.json`'s `compilerOptions` suppresses the warning.
+
+| Option in your `tsconfig.json`                          | In Deno                                                                                                                                    |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `target`, `outDir`, `outFile`, `rootDir`                | Delete. Deno never emits: code runs directly on the latest V8, and `deno check` type-checks without producing output.                      |
+| `declaration`, `declarationMap`, `emitDeclarationOnly`  | Delete. No emit. Use [`deno doc`](/runtime/reference/cli/doc/) for API documentation.                                                      |
+| `sourceMap`, `inlineSourceMap`, `inlineSources`         | Delete. Stack traces map to your TypeScript sources automatically.                                                                         |
+| `esModuleInterop`, `allowSyntheticDefaultImports`       | Delete. Deno is ESM-native and handles CommonJS interop in the runtime.                                                                    |
+| `importHelpers`, `noEmitHelpers`, `downlevelIteration`  | Delete. No downleveling happens, so no helpers are emitted.                                                                                |
+| `resolveJsonModule`                                     | Delete. Import JSON with an attribute instead: `import data from "./data.json" with { type: "json" }`.                                     |
+| `skipLibCheck`                                          | Delete. Deno does not type-check dependencies by default (`deno check --all` opts in).                                                     |
+| `module`, `moduleResolution`                            | Usually delete. Deno defaults to `nodenext`; the supported values are listed in the table below.                                           |
+| `lib`, `types`                                          | Usually delete. Deno's defaults cover its runtime; keep `lib` only for cross-runtime code (see ["lib" property](#using-the-lib-property)). |
+| `strict`, `noImplicit*`, `noUnused*`, other check flags | Keep the ones you want, in `deno.json`'s `compilerOptions`. Note Deno's defaults are already strict (table below).                         |
+| `paths`, `baseUrl`                                      | Keep if needed for type-time path mapping, or replace with [import maps](/runtime/fundamentals/modules/), which also work at runtime.      |
+
 ## TS Compiler Options
 
 Here is a table of compiler options that can be changed, their default in Deno
@@ -179,8 +201,8 @@ using any APIs exclusive to one or the other. In such cases, a typical
 
 This should allow most code to be type checked properly by Deno.
 
-If you expect to run the code in Deno with the `--unstable` flag, then you
-should add that library to the mix as well:
+If your code uses APIs that are gated behind one of the `--unstable-*` flags,
+add the `deno.unstable` library to the mix as well:
 
 ```json title="deno.json"
 {

runtime/run/index.md

@@ -30,30 +30,19 @@ access to the network, filesystem, environment, or subprocesses** until you
 grant it. A script that tries to read a file without permission stops and asks,
 or fails if prompts are disabled.
 
-Grant access with `--allow-*` flags (each has a short form):
+Grant access with `--allow-*` flags (each has a short form), and scope them down
+to exactly what's needed:
 
 ```sh
-deno run --allow-net main.ts        # network    (-N)
-deno run --allow-read main.ts       # filesystem (-R)
-deno run --allow-env main.ts        # env vars   (-E)
-```
-
-Scope them down to exactly what's needed, and combine as required:
-
-```sh
-deno run --allow-read=./data --allow-net=api.example.com main.ts
+deno run --allow-net main.ts                     # network    (-N)
+deno run --allow-read=./data main.ts             # filesystem (-R), scoped
+deno run -N=api.example.com -E main.ts           # combined, short forms
 ```
 
 Use `--deny-*` to carve out exceptions, or `-A` / `--allow-all` to skip the
-sandbox entirely (handy in trusted environments, but it gives up the
-guarantees):
-
-```sh
-deno run -A main.ts
-```
-
-See [Permissions](/runtime/reference/permissions/) for every flag and
-[Security](/runtime/fundamentals/security/) for the model behind them.
+sandbox entirely. That is handy in trusted environments, but it gives up the
+guarantees. See [Permissions](/runtime/reference/permissions/) for every flag
+and [Security](/runtime/fundamentals/security/) for the model behind them.
 
 ## Run from a URL or stdin
 
@@ -77,7 +66,9 @@ changes. No `nodemon`, no extra dependency:
 deno run --watch main.ts
 ```
 
-`deno test`, `deno fmt`, and others accept `--watch` too.
+`deno test`, `deno fmt`, and others accept `--watch` too. For what gets watched,
+excluding paths, and hot module replacement, see the
+[CLI patterns page](/runtime/getting_started/command_line_interface/#watch-mode).
 
 ## Run project tasks