Merge branch 'main' into docs/deno-spawn-apis

Author: thisisjofrank

examples/_data.ts

@@ -166,6 +166,11 @@ export const sidebar = [
           "https://www.youtube.com/watch?v=oxVwTT-rZRo&list=PLvvLnBDNuTEov9EBIp3MMfHlBxaKGRWTe&index=6",
         type: "video",
       },
+      {
+        title: "Temporal API",
+        href: "/examples/temporal/",
+        type: "example",
+      },
       {
         title: "Better debugging with the console API",
         href: "/examples/debugging_with_console_tutorial/",
@@ -1077,11 +1082,6 @@ export const sidebar = [
         href: "/examples/udp_connector/",
         type: "example",
       },
-      {
-        title: "Temporal API",
-        href: "/examples/temporal/",
-        type: "example",
-      },
       {
         title: "Importing text",
         href: "/examples/importing_text/",

examples/scripts/temporal.ts

@@ -2,10 +2,10 @@
  * @title Temporal API
  * @difficulty beginner
  * @tags cli
- * @run --unstable-temporal <url>
+ * @run <url>
  * @resource {https://docs.deno.com/api/web/~/Temporal} Temporal API reference documentation
  * @resource {https://tc39.es/proposal-temporal/docs} Temporal API proposal documentation
- * @group Unstable APIs
+ * @group Web APIs
  */
 
 // Get the current date

runtime/_data.ts

@@ -128,6 +128,10 @@ export const sidebar = [
             title: "deno compile",
             href: "/runtime/reference/cli/compile/",
           },
+          {
+            title: "deno create",
+            href: "/runtime/reference/cli/create/",
+          },
           {
             title: "deno completions",
             href: "/runtime/reference/cli/completions/",

runtime/fundamentals/configuration.md

@@ -527,11 +527,22 @@ import * as module_2 from "@example/my-package/module2";
 
 ## Permissions
 
-Deno 2.5+ supports storing permission sets in the config file.
+Deno 2.5+ supports storing
+[permission](/runtime/fundamentals/security/#permissions) sets in the config
+file.
 
 ### Named permissions
 
-Permissions can be defined in key value pairs under the `"permissions"` key:
+Permissions can be defined as key-value pairs under arbitrarily-named permission
+sets under the `"permissions"` key. Within each set,
+
+- the key is the name of a
+  [permission](/runtime/fundamentals/security/#permissions) that would follow
+  `--allow-` or `--deny-` in the CLI invocation (i.e. `read`, `write`, `net`,
+  `env`, `sys`, `run`, `ffi`, `import`)
+- the value is a boolean (`true` / `false` correspond to allow / deny), an array
+  of strings representing paths, domains etc., or an object with `allow`,
+  `deny`, and/or `ignore` boolean key-value pairs.
 
 ```jsonc
 {
@@ -547,7 +558,8 @@ Permissions can be defined in key value pairs under the `"permissions"` key:
 }
 ```
 
-Then used by specifying the `--permission-set=<name>` or `-P=<name>` flag:
+Permission sets can be used by specifying the `--permission-set=<name>` or
+`-P=<name>` flag:
 
 ```sh
 $ deno run -P=read-data main.ts

runtime/fundamentals/debugging.md

@@ -201,3 +201,16 @@ including:
 For full details on Deno's OpenTelemetry integration, including custom metrics,
 traces, and configuration options, see the
 [OpenTelemetry documentation](/runtime/fundamentals/open_telemetry).
+
+## TLS session debugging
+
+Set the `SSLKEYLOGFILE` environment variable to log TLS session keys to a file.
+This enables you to decrypt and inspect encrypted network traffic with tools
+like [Wireshark](https://www.wireshark.org/):
+
+```sh
+SSLKEYLOGFILE=./keys.log deno run -N main.ts
+```
+
+Then load `keys.log` in Wireshark (Edit > Preferences > Protocols > TLS >
+(Pre)-Master-Secret log filename) to decrypt captured TLS traffic.

runtime/reference/cli/check.md

@@ -7,9 +7,9 @@ openGraphTitle: "deno check"
 description: "Download and type-check code without execution"
 ---
 
-## Example
+## Examples
 
-Type-check without execution.
+Type-check a TypeScript file without execution:
 
 ```ts title="example.ts"
 const x: string = 1 + 1n;
@@ -18,3 +18,13 @@ const x: string = 1 + 1n;
 ```bash
 deno check example.ts
 ```
+
+## Type-checking JavaScript files
+
+If you have a JavaScript-only project and want to type-check it with Deno, you
+can use the `--check-js` flag instead of adding `// @ts-check` to every file or
+setting `compilerOptions.checkJs` in your `deno.json`:
+
+```bash
+deno check --check-js main.js
+```

runtime/reference/cli/compile.md

@@ -152,7 +152,7 @@ addons or native code that reads relative files.
 
 The extraction directory is chosen in order of preference:
 
-1. `<exe_dir>/<exe_name>.fs/<hash>/` (next to the compiled binary)
+1. `<exe_dir>/.<exe_name>/<hash>/` (next to the compiled binary)
 2. Platform data directory fallback:
    - Linux: `$XDG_DATA_HOME/<exe_name>/<hash>` or
      `~/.local/share/<exe_name>/<hash>`

runtime/reference/cli/create.md

@@ -0,0 +1,76 @@
+---
+title: "deno create, scaffold a new project"
+command: create
+openGraphLayout: "/open_graph/cli-commands.jsx"
+openGraphTitle: "deno create"
+description: "Scaffold a new project from a template package"
+---
+
+The `deno create` command scaffolds a new project from a template package. It
+works with both [JSR](https://jsr.io/) and [npm](https://www.npmjs.com/)
+packages that provide project templates.
+
+## Usage
+
+```sh
+deno create [OPTIONS] [PACKAGE] [-- [ARGS]...]
+```
+
+By default, unprefixed package names are resolved from JSR. You can use the
+`npm:` or `jsr:` prefix to be explicit, or use the `--npm` / `--jsr` flags.
+
+## How it works
+
+Package resolution differs between npm and JSR:
+
+- **npm packages** use the `create-` naming convention. Running
+  `deno create npm:vite` resolves to the `create-vite` package on npm and
+  executes its main entry point.
+- **JSR packages** use the `./create` export. Any JSR package can act as a
+  template by defining a `./create` entry point in its `deno.json`:
+
+```json title="deno.json"
+{
+  "name": "@my-scope/my-template",
+  "version": "1.0.0",
+  "exports": {
+    ".": "./mod.ts",
+    "./create": "./create.ts"
+  }
+}
+```
+
+When you run `deno create @my-scope/my-template`, Deno looks for the `./create`
+export and runs it as the scaffolding script.
+
+## Examples
+
+Create a project from a JSR package:
+
+```sh
+deno create @fresh/init
+```
+
+Create a project from an npm package:
+
+```sh
+deno create npm:vite my-app
+```
+
+Using the `--npm` flag to treat unprefixed names as npm packages:
+
+```sh
+deno create --npm create-vite my-app
+```
+
+Pass arguments to the template package:
+
+```sh
+deno create @fresh/init -- --force
+```
+
+## Flags
+
+- `--npm` - Treat unprefixed package names as npm packages
+- `--jsr` - Treat unprefixed package names as JSR packages (default)
+- `-y, --yes` - Bypass the prompt and run with full permissions

runtime/reference/cli/fmt.md

@@ -57,6 +57,16 @@ enclosed in triple backticks and have a language attribute.
 
 :::
 
+## Checking formatting in CI
+
+Use `--check` to verify files are formatted without modifying them. Add
+`--fail-fast` to stop on the first unformatted file instead of reporting all of
+them, which is useful in large codebases:
+
+```sh
+deno fmt --check --fail-fast
+```
+
 ## Ignoring Code
 
 ### JavaScript / TypeScript / JSONC

runtime/reference/cli/index.md

@@ -45,6 +45,8 @@ below for more information on each subcommand.
   completions
 - [deno coverage](/runtime/reference/cli/coverage/) - generate test coverage
   reports
+- [deno create](/runtime/reference/cli/create/) - scaffold a new project from a
+  template
 - [deno doc](/runtime/reference/cli/doc/) - generate documentation for a module
 - [deno deploy](/runtime/reference/cli/deploy) - Manage and publish your
   projects on the web