Merge remote-tracking branch 'origin/main' into worktree-agent-a388cc1de15e55ebb

Author: bartlomieju

js/tabs.ts

@@ -79,6 +79,15 @@ for (const tabGroup of document.querySelectorAll<HTMLElement>(".deno-tabs")) {
   const storedTabId = localStorage.getItem(`deno-tab-${groupId}`);
   if (storedTabId) {
     document.dispatchEvent(new GroupSelectEvent(groupId, storedTabId));
+  } else if (groupId === "operating-systems") {
+    const ua = navigator.userAgent;
+    let detected: string | null = null;
+    if (/Mac/i.test(ua)) detected = "mac";
+    else if (/Win/i.test(ua)) detected = "windows";
+    else if (/Linux/i.test(ua)) detected = "linux";
+    if (detected) {
+      document.dispatchEvent(new GroupSelectEvent(groupId, detected));
+    }
   }
 
   const anyTabActive = Array.from(tabs).some((tab) =>

runtime/getting_started/first_project.md

@@ -1,19 +1,14 @@
 ---
-last_modified: 2025-03-10
+last_modified: 2026-05-28
 title: Making a Deno project
 description: "Step-by-step guide to creating your first Deno project. Learn how to initialize a project, understand the basic file structure, run TypeScript code, and execute tests using Deno's built-in test runner."
 oldUrl: /runtime/manual/getting_started/first_steps/
 ---
 
-Deno has many [built in tools](/runtime/reference/cli/) to make your development
-experience as smooth as possible. One of these tools is the
-[project initializer](/runtime/reference/cli/init), which creates a new Deno
-project with a basic file structure and configuration.
-
-While you are welcome to use JavaScript, Deno has built-in support for
-[TypeScript](https://www.typescriptlang.org/) as well, so we'll be using
-TypeScript in this guide. If you'd prefer to use JavaScript, you can rename the
-files to `.js` and remove the type annotations.
+In this guide, you'll create your first Deno project, run it, and execute its
+tests. We'll use [TypeScript](https://www.typescriptlang.org/) throughout. To
+follow along in JavaScript instead, rename the files to `.js` and remove the
+type annotations.
 
 ## Initialize a new project
 
@@ -33,31 +28,33 @@ my_project
 └── main.ts
 ```
 
-A `deno.json` file is created to
-[configure your project](/runtime/fundamentals/configuration/), and two
-TypeScript files are created; `main.ts` and `main_test.ts`. As of Deno 2.8 the
-`main.ts` file contains a small HTTP server built on
-[`Deno.serve`](/api/deno/~/Deno.serve) — it shows off Deno's built-in HTTP
-server, `Response.json()`, and TypeScript working out of the box. The handler is
-exported and guarded by `import.meta.main`, so `main_test.ts` can import and
-call it directly without binding to a port.
+[`deno.json`](/runtime/fundamentals/configuration/) holds your project
+configuration. `main.ts` is a small HTTP server built on
+[`Deno.serve`](/api/deno/~/Deno.serve), and `main_test.ts` has the tests for it.
 
 ## Run your project
 
+Move into the new project directory:
+
+```bash
+cd my_project
+```
+
 You can run this program with the following command:
 
 ```bash
-$ deno main.ts
+$ deno -N main.ts
 Listening on http://localhost:8000/
 ```
 
+The server needs network permission, granted here via `-N` (short for
+`--allow-net`). See [security](/runtime/fundamentals/security/) for more.
+
 Open the URL in your browser to see the response.
 
 ## Run your tests
 
-Deno has a [built in test runner](/runtime/fundamentals/testing/). You can write
-tests for your code and run them with the `deno test` command. Run the tests in
-your new project with:
+Run the tests with [`deno test`](/runtime/fundamentals/testing/):
 
 ```bash
 $ deno test
@@ -68,9 +65,4 @@ handler returns 404 for unknown route ... ok (1ms)
 ok | 2 passed | 0 failed (3ms)
 ```
 
-Now that you have a basic project set up you can start building your
-application. Check out our [examples and tutorials](/examples/) for more ideas
-on what to build with Deno.
-
-You can
-[learn more about using TypeScript in Deno here](/runtime/fundamentals/typescript).
+Browse our [examples and tutorials](/examples/) for ideas on what to build next.

runtime/getting_started/installation.md

@@ -8,18 +8,16 @@ oldUrl:
   - /runtime/fundamentals/installation
 ---
 
-Deno works on macOS, Linux, and Windows. Deno is a single binary executable. It
-has no external dependencies. On macOS, both M1 (arm64) and Intel (x64)
-executables are provided. On Windows, both ARM64 and x64 are supported. On
-Linux, only x64 is supported.
+Deno is a single binary executable with no external dependencies. It runs on
+macOS, Linux, and Windows, on both x64 and arm64 architectures.
 
 ## Download and install
 
 [deno_install](https://github.com/denoland/deno_install) provides convenience
 scripts to download and install the binary.
 
 <deno-tabs group-id="operating-systems">
-<deno-tab value="mac" label="macOS" default>
+<deno-tab value="linux" label="Linux">
 
 Using Shell:
 
@@ -33,52 +31,43 @@ Using [npm](https://npmjs.com/package/deno):
 npm install -g deno
 ```
 
-> <small>The startup time of the Deno command gets affected if it's installed
-> via npm. We recommend the shell install script for better performance.</small>
-
-Using [Homebrew](https://formulae.brew.sh/formula/deno):
+Using [Nix](https://nixos.org/download.html):
 
 ```shell
-brew install deno
+nix-shell -p deno
 ```
 
-Using [MacPorts](https://ports.macports.org/port/deno/):
+</deno-tab>
+<deno-tab value="mac" label="macOS" default>
+
+Using Shell:
 
 ```shell
-sudo port install deno
+curl -fsSL https://deno.land/install.sh | sh
 ```
 
-Using [Nix](https://nixos.org/download.html):
+Using [npm](https://npmjs.com/package/deno):
 
 ```shell
-nix-shell -p deno
+npm install -g deno
 ```
 
-Using [asdf](https://asdf-vm.com/):
+Using [Homebrew](https://formulae.brew.sh/formula/deno):
 
 ```shell
-asdf plugin add deno https://github.com/asdf-community/asdf-deno.git
-
-# Download and install the latest version of Deno
-asdf install deno latest
-
-# To set as the default version of Deno globally
-asdf set -u deno latest
-
-# To set as the default version of Deno locally (current project only)
-asdf set deno latest
+brew install deno
 ```
 
-Using [vfox](https://vfox.dev/):
+Using [MacPorts](https://ports.macports.org/port/deno/):
 
 ```shell
-vfox add deno
+sudo port install deno
+```
 
-# Download and install the latest version of Deno
-vfox install deno@latest
+Using [Nix](https://nixos.org/download.html):
 
-# To set the version of Deno globally
-vfox use --global deno
+```shell
+nix-shell -p deno
 ```
 
 </deno-tab>
@@ -100,10 +89,6 @@ Using [npm](https://npmjs.com/package/deno):
 npm install -g deno
 ```
 
-> <small>The startup time of the Deno command gets affected if it's installed
-> via npm. We recommend the PowerShell install script for better
-> performance.</small>
-
 Using [Scoop](https://scoop.sh/):
 
 ```shell
@@ -122,41 +107,16 @@ Using [Winget](https://github.com/microsoft/winget-cli):
 winget install DenoLand.Deno
 ```
 
-Using [vfox](https://vfox.dev/):
-
-```shell
-vfox add deno
-
-# Download and install the latest version of Deno
-vfox install deno@latest
-
-# To set the version of Deno globally
-vfox use --global deno
-```
-
 </deno-tab>
-<deno-tab value="linux" label="Linux">
-
-Using Shell:
-
-```shell
-curl -fsSL https://deno.land/install.sh | sh
-```
-
-Using [npm](https://npmjs.com/package/deno):
-
-```shell
-npm install -g deno
-```
+</deno-tabs>
 
 > <small>The startup time of the Deno command gets affected if it's installed
-> via npm. We recommend the shell install script for better performance.</small>
+> via npm. We recommend the official install script (shell or PowerShell) for
+> better performance.</small>
 
-Using [Nix](https://nixos.org/download.html):
+### Cross-platform package managers
 
-```shell
-nix-shell -p deno
-```
+These version managers work on macOS, Linux, and Windows.
 
 Using [asdf](https://asdf-vm.com/):
 
@@ -185,9 +145,6 @@ vfox install deno@latest
 vfox use --global deno
 ```
 
-</deno-tab>
-</deno-tabs>
-
 You can also build and install from source using
 [Cargo](https://crates.io/crates/deno):
 
@@ -273,6 +230,24 @@ To update a previously installed version of Deno, you can run:
 deno upgrade
 ```
 
+Or using [Homebrew](https://formulae.brew.sh/formula/deno) (macOS):
+
+```shell
+brew upgrade deno
+```
+
+Or using [Scoop](https://scoop.sh/) (Windows):
+
+```shell
+scoop update deno
+```
+
+Or using [Chocolatey](https://chocolatey.org/packages/deno) (Windows):
+
+```shell
+choco upgrade deno
+```
+
 Or using [Winget](https://github.com/microsoft/winget-cli) (Windows):
 
 ```shell
@@ -286,7 +261,7 @@ unzip it, and replace your current executable with it.
 You can also use this utility to install a specific version of Deno:
 
 ```shell
-deno upgrade --version 1.0.1
+deno upgrade --version 2.7.0
 ```
 
 ## Uninstalling
@@ -307,8 +282,10 @@ Then remove the Deno installation directory:
 rm -rf ~/.deno
 ```
 
-Finally, remove the `DENO_INSTALL` export and `PATH` entry from your shell
-config file (`~/.bashrc`, `~/.zshrc`, `~/.config/fish/config.fish`, etc.).
+Finally, remove the line that sources Deno's env file from your shell config
+(`~/.bashrc`, `~/.zshrc`, `~/.profile`, etc.). The shell install script appends
+a line like `. "$HOME/.deno/env"` — delete that line. Fish users should
+additionally remove `~/.config/fish/conf.d/deno.fish`.
 
 </deno-tab>
 <deno-tab value="windows" label="Windows">