From 185c3bfdbf0d76f5e5fdc2a180fefad5fa8c0e11 Mon Sep 17 00:00:00 2001 From: zqleslie <17967998@qq.com> Date: Fri, 22 May 2026 06:45:09 +0800 Subject: [PATCH 1/8] docs: add command resolution section to task runner docs Documents how `deno task` resolves commands: 1. node_modules/.bin/ 2. package.json bin field 3. System PATH Also documents the Deno equivalent of `npx`. Fixes denoland/deno#26523 --- runtime/reference/cli/task.md | 60 +++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/runtime/reference/cli/task.md b/runtime/reference/cli/task.md index 76f724761..4983493e6 100644 --- a/runtime/reference/cli/task.md +++ b/runtime/reference/cli/task.md @@ -662,3 +662,63 @@ file if it is discovered. Note that Deno does not respect or support any npm life cycle events like `preinstall` or `postinstall`—you must explicitly run the script entries you want to run (ex. `deno install --entrypoint main.ts && deno task postinstall`). + + +## Command Resolution + +When a task command references a binary (e.g., `ohm`, `tsc`, `eslint`), Deno resolves it +using the following order: + +1. **Workspace `node_modules/.bin/`** - If a `node_modules` directory exists (from `deno install` + or `deno add`), Deno will look for the binary in `node_modules/.bin/`. This is compatible + with how `npx` works in the Node.js ecosystem. + +2. **Package.json `bin` field** - When a dependency defines a `bin` field in its + `package.json`, Deno automatically makes those commands available within task scripts. + This is resolved through Deno's npm compatibility layer. + +3. **System PATH** - If the command is not found in `node_modules/.bin/`, Deno falls back + to searching the system PATH. + +### Example + +Given a `package.json` with: + +```json +{ + "dependencies": { + "@ohm-js/cli": "^2.0.0" + } +} +``` + +And a `deno.json` with: + +```json +{ + "tasks": { + "generate": "ohm src/grammar.ohm -o src/grammar.js" + } +} +``` + +Running `deno task generate` will: + +1. Look for `ohm` in `node_modules/.bin/ohm` +2. If found, execute it using Deno's Node.js compatibility layer +3. The command runs under Deno's runtime, not Node.js + +### Deno's Equivalent to `npx` + +The equivalent of `npx ` in Deno is: + +```bash +deno run -A npm:@latest +``` + +For example: +- `npx cowsay hello` → `deno run -A npm:cowsay@latest hello` +- `npx create-react-app my-app` → `deno run -A npm:create-react-app@latest my-app` + +You can also use `deno add npm:` to add an npm dependency and then reference +its binaries in `deno task` scripts. From 63a9a704d00b860cc5b6550618c3a14bd85dc45d Mon Sep 17 00:00:00 2001 From: zqleslie <17967998@qq.com> Date: Fri, 22 May 2026 06:58:52 +0800 Subject: [PATCH 2/8] fix: formatting cleanup for deno fmt compliance --- runtime/reference/cli/task.md | 38 +++++++++++++++++------------------ 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/runtime/reference/cli/task.md b/runtime/reference/cli/task.md index 4983493e6..7d4011615 100644 --- a/runtime/reference/cli/task.md +++ b/runtime/reference/cli/task.md @@ -146,13 +146,13 @@ Dependency tasks are executed in parallel, with the default parallel limit being equal to number of cores on your machine. To change this limit, use the `DENO_JOBS` environmental variable. -Dependencies are tracked and if multiple tasks depend on the same task, that +Dependencies are tracked and if multiple tasks depend on the same task, tha task will only be run once: ```jsonc title="deno.json" { // a - // / \ + // / // b c // \ / // d @@ -225,7 +225,7 @@ useful to logically group several tasks together: Running `deno task dev` will run both `dev:client` and `dev:server` in parallel. -## Node and npx binary support +## Node and npx binary suppor By default, `deno task` will execute commands with the `deno` binary. If you need to ensure that a command is run with the `npm` or `npx` binary, you can do @@ -239,7 +239,7 @@ so by invoking the `npm` or `npx` `run` command respectively. For example: } ``` -## Workspace support +## Workspace suppor `deno task` can be used in workspaces, to run tasks from multiple member directories in parallel. To execute `dev` tasks from all workspace members use @@ -301,7 +301,7 @@ defined tasks. ### Boolean lists -Boolean lists provide a way to execute additional commands based on the exit +Boolean lists provide a way to execute additional commands based on the exi code of the initial command. They separate commands using the `&&` and `||` operators. @@ -409,7 +409,7 @@ hello Deno: undefined ``` -Shell variables can be useful when we want to reuse a value, but don't want it +Shell variables can be useful when we want to reuse a value, but don't want i available in any spawned processes. ### Exit status variable @@ -473,26 +473,26 @@ For example, the following redirects _stdout_ of `deno run main.ts` to a file called `file.txt` on the file system: ```sh -deno run main.ts > file.txt +deno run main.ts > file.tx ``` To instead redirect _stderr_, use `2>`: ```sh -deno run main.ts 2> file.txt +deno run main.ts 2> file.tx ``` To redirect both stdout _and_ stderr, use `&>`: ```sh -deno run main.ts &> file.txt +deno run main.ts &> file.tx ``` To append to a file, instead of overwriting an existing one, use two right angle brackets instead of one: ```sh -deno run main.ts >> file.txt +deno run main.ts >> file.tx ``` Suppressing either stdout, stderr, or both of a command is possible by @@ -500,7 +500,7 @@ redirecting to `/dev/null`. This works in a cross-platform way including on Windows. ```sh -# suppress stdout +# suppress stdou deno run main.ts > /dev/null # suppress stderr deno run main.ts 2> /dev/null @@ -513,7 +513,7 @@ Or redirecting stdout to stderr and vice-versa: ```sh # redirect stdout to stderr deno run main.ts >&2 -# redirect stderr to stdout +# redirect stderr to stdou deno run main.ts 2>&1 ``` @@ -521,7 +521,7 @@ Input redirects are also supported: ```sh # redirect file.txt to the stdin of gzip -gzip < file.txt +gzip < file.tx ``` Note that redirecting multiple redirects is currently not supported. @@ -550,7 +550,7 @@ Then on a Windows machine: ```sh > pwd -C:\Users\david\dev\my_project +C:\Users\david\dev\my_projec > deno task hi Hello there! ``` @@ -584,7 +584,7 @@ enabled. - **nullglob** - When enabled, globs that don't match any files expand to nothing instead of the literal glob pattern. Enable with `shopt -s nullglob`. - **pipefail** - When enabled, the exit code of a pipeline is the exit code of - the last command to exit with a non-zero status, or zero if all commands exit + the last command to exit with a non-zero status, or zero if all commands exi successfully. Enable with `set -o pipefail`. Examples: @@ -639,7 +639,7 @@ box on Windows, Mac, and Linux. outputs stdin. - [`exit`](https://man7.org/linux/man-pages/man1/exit.1p.html) - Causes the shell to exit. -- [`head`](https://man7.org/linux/man-pages/man1/head.1.html) - Output the first +- [`head`](https://man7.org/linux/man-pages/man1/head.1.html) - Output the firs part of a file. - [`unset`](https://man7.org/linux/man-pages/man1/unset.1p.html) - Unsets environment variables. @@ -655,7 +655,7 @@ Note that if you wish to execute any of these commands in a non-cross-platform way on Mac or Linux, then you may do so by running it through `sh`: `sh -c ` (ex. `sh -c cp source destination`). -## package.json support +## package.json suppor `deno task` falls back to reading from the `"scripts"` entries in a package.json file if it is discovered. Note that Deno does not respect or support any npm @@ -666,7 +666,7 @@ script entries you want to run (ex. ## Command Resolution -When a task command references a binary (e.g., `ohm`, `tsc`, `eslint`), Deno resolves it +When a task command references a binary (e.g., `ohm`, `tsc`, `eslint`), Deno resolves i using the following order: 1. **Workspace `node_modules/.bin/`** - If a `node_modules` directory exists (from `deno install` @@ -713,7 +713,7 @@ Running `deno task generate` will: The equivalent of `npx ` in Deno is: ```bash -deno run -A npm:@latest +deno run -A npm:@lates ``` For example: From b4b95ca9fd2714def589c7ea33a71e8024b5b8eb Mon Sep 17 00:00:00 2001 From: zqleslie <17967998@qq.com> Date: Fri, 22 May 2026 07:17:19 +0800 Subject: [PATCH 3/8] fix: remove trailing whitespace for deno fmt compliance From 304786443d34f657ca2f4c8b52b39b3d725aa957 Mon Sep 17 00:00:00 2001 From: zqleslie <17967998@qq.com> Date: Fri, 22 May 2026 08:52:15 +0800 Subject: [PATCH 4/8] fix: wrap Command Resolution prose to 80 chars for deno fmt --- runtime/reference/cli/task.md | 37 +++++++++++++++++++---------------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/runtime/reference/cli/task.md b/runtime/reference/cli/task.md index 7d4011615..5f070f472 100644 --- a/runtime/reference/cli/task.md +++ b/runtime/reference/cli/task.md @@ -663,22 +663,23 @@ life cycle events like `preinstall` or `postinstall`—you must explicitly run t script entries you want to run (ex. `deno install --entrypoint main.ts && deno task postinstall`). - ## Command Resolution -When a task command references a binary (e.g., `ohm`, `tsc`, `eslint`), Deno resolves i -using the following order: +When a task command references a binary (e.g., `ohm`, `tsc`, `eslint`), +Deno resolves it using the following order: -1. **Workspace `node_modules/.bin/`** - If a `node_modules` directory exists (from `deno install` - or `deno add`), Deno will look for the binary in `node_modules/.bin/`. This is compatible - with how `npx` works in the Node.js ecosystem. +1. **Workspace `node_modules/.bin/`** - If a `node_modules` directory + exists (from `deno install` or `deno add`), Deno will look for the + binary in `node_modules/.bin/`. This is compatible with how `npx` + works in the Node.js ecosystem. -2. **Package.json `bin` field** - When a dependency defines a `bin` field in its - `package.json`, Deno automatically makes those commands available within task scripts. - This is resolved through Deno's npm compatibility layer. +2. **Package.json `bin` field** - When a dependency defines a `bin` + field in its `package.json`, Deno automatically makes those commands + available within task scripts. This is resolved through Deno's npm + compatibility layer. -3. **System PATH** - If the command is not found in `node_modules/.bin/`, Deno falls back - to searching the system PATH. +3. **System PATH** - If the command is not found in `node_modules/.bin/`, + Deno falls back to searching the system PATH. ### Example @@ -706,19 +707,21 @@ Running `deno task generate` will: 1. Look for `ohm` in `node_modules/.bin/ohm` 2. If found, execute it using Deno's Node.js compatibility layer -3. The command runs under Deno's runtime, not Node.js +3. The command runs under Deno's runtime, not Node.js. ### Deno's Equivalent to `npx` The equivalent of `npx ` in Deno is: ```bash -deno run -A npm:@lates +deno run -A npm:@latest ``` For example: -- `npx cowsay hello` → `deno run -A npm:cowsay@latest hello` -- `npx create-react-app my-app` → `deno run -A npm:create-react-app@latest my-app` -You can also use `deno add npm:` to add an npm dependency and then reference -its binaries in `deno task` scripts. +- `npx cowsay hello` -> `deno run -A npm:cowsay@latest hello` +- `npx create-react-app my-app` -> + `deno run -A npm:create-react-app@latest my-app` + +You can also use `deno add npm:` to add an npm dependency and +then reference its binaries in `deno task` scripts. From 0ff52021bb9ee85245f2bf0e696b7521d37a7f51 Mon Sep 17 00:00:00 2001 From: zqleslie Date: Fri, 22 May 2026 09:35:34 +0800 Subject: [PATCH 5/8] fix: apply deno fmt to resolve lint CI failure --- runtime/reference/cli/task.md | 39 +++++++++++++++++------------------ 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/runtime/reference/cli/task.md b/runtime/reference/cli/task.md index 5f070f472..2b6e8074d 100644 --- a/runtime/reference/cli/task.md +++ b/runtime/reference/cli/task.md @@ -98,8 +98,8 @@ Running `deno task "build:*"` will run both `build:client` and `build:server` tasks. For multi-word task names, we recommend using `:` as the separator (e.g. -`build:client`, `test:unit`, `lint:fix`) to match the convention used in the -npm ecosystem and to group related tasks for wildcard matching. +`build:client`, `test:unit`, `lint:fix`) to match the convention used in the npm +ecosystem and to group related tasks for wildcard matching. :::note @@ -146,8 +146,8 @@ Dependency tasks are executed in parallel, with the default parallel limit being equal to number of cores on your machine. To change this limit, use the `DENO_JOBS` environmental variable. -Dependencies are tracked and if multiple tasks depend on the same task, tha -task will only be run once: +Dependencies are tracked and if multiple tasks depend on the same task, tha task +will only be run once: ```jsonc title="deno.json" { @@ -301,8 +301,8 @@ defined tasks. ### Boolean lists -Boolean lists provide a way to execute additional commands based on the exi -code of the initial command. They separate commands using the `&&` and `||` +Boolean lists provide a way to execute additional commands based on the exi code +of the initial command. They separate commands using the `&&` and `||` operators. The `&&` operator provides a way to execute a command and if it _succeeds_ (has @@ -665,21 +665,20 @@ script entries you want to run (ex. ## Command Resolution -When a task command references a binary (e.g., `ohm`, `tsc`, `eslint`), -Deno resolves it using the following order: +When a task command references a binary (e.g., `ohm`, `tsc`, `eslint`), Deno +resolves it using the following order: -1. **Workspace `node_modules/.bin/`** - If a `node_modules` directory - exists (from `deno install` or `deno add`), Deno will look for the - binary in `node_modules/.bin/`. This is compatible with how `npx` - works in the Node.js ecosystem. +1. **Workspace `node_modules/.bin/`** - If a `node_modules` directory exists + (from `deno install` or `deno add`), Deno will look for the binary in + `node_modules/.bin/`. This is compatible with how `npx` works in the Node.js + ecosystem. -2. **Package.json `bin` field** - When a dependency defines a `bin` - field in its `package.json`, Deno automatically makes those commands - available within task scripts. This is resolved through Deno's npm - compatibility layer. +2. **Package.json `bin` field** - When a dependency defines a `bin` field in its + `package.json`, Deno automatically makes those commands available within task + scripts. This is resolved through Deno's npm compatibility layer. -3. **System PATH** - If the command is not found in `node_modules/.bin/`, - Deno falls back to searching the system PATH. +3. **System PATH** - If the command is not found in `node_modules/.bin/`, Deno + falls back to searching the system PATH. ### Example @@ -723,5 +722,5 @@ For example: - `npx create-react-app my-app` -> `deno run -A npm:create-react-app@latest my-app` -You can also use `deno add npm:` to add an npm dependency and -then reference its binaries in `deno task` scripts. +You can also use `deno add npm:` to add an npm dependency and then +reference its binaries in `deno task` scripts. From 1b281fb78fd8debf1b76195aadbf40e4e2abc8a2 Mon Sep 17 00:00:00 2001 From: zqleslie <17967998@qq.com> Date: Fri, 22 May 2026 22:11:28 +0800 Subject: [PATCH 6/8] docs(task): fix truncation regressions and correct node_modules description - Restore truncated words: 'the task', 'binary support', 'Workspace support', 'exit code', 'don't want it', 'my_project', 'commands exit', 'Output the first', 'package.json support', 'stdout' - Fix redirect examples: file.txt (not file.tx) - Correct node_modules description for Deno 2.7+: deno add does not create node_modules, only updates deno.json imports and deno.lock --- runtime/reference/cli/task.md | 47 ++++++++++++++++++----------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/runtime/reference/cli/task.md b/runtime/reference/cli/task.md index 2b6e8074d..45c5279e9 100644 --- a/runtime/reference/cli/task.md +++ b/runtime/reference/cli/task.md @@ -146,7 +146,7 @@ Dependency tasks are executed in parallel, with the default parallel limit being equal to number of cores on your machine. To change this limit, use the `DENO_JOBS` environmental variable. -Dependencies are tracked and if multiple tasks depend on the same task, tha task +Dependencies are tracked and if multiple tasks depend on the same task, the task will only be run once: ```jsonc title="deno.json" @@ -225,7 +225,7 @@ useful to logically group several tasks together: Running `deno task dev` will run both `dev:client` and `dev:server` in parallel. -## Node and npx binary suppor +## Node and npx binary support By default, `deno task` will execute commands with the `deno` binary. If you need to ensure that a command is run with the `npm` or `npx` binary, you can do @@ -239,7 +239,7 @@ so by invoking the `npm` or `npx` `run` command respectively. For example: } ``` -## Workspace suppor +## Workspace support `deno task` can be used in workspaces, to run tasks from multiple member directories in parallel. To execute `dev` tasks from all workspace members use @@ -301,7 +301,7 @@ defined tasks. ### Boolean lists -Boolean lists provide a way to execute additional commands based on the exi code +Boolean lists provide a way to execute additional commands based on the exit code of the initial command. They separate commands using the `&&` and `||` operators. @@ -409,7 +409,7 @@ hello Deno: undefined ``` -Shell variables can be useful when we want to reuse a value, but don't want i +Shell variables can be useful when we want to reuse a value, but don't want it available in any spawned processes. ### Exit status variable @@ -473,26 +473,26 @@ For example, the following redirects _stdout_ of `deno run main.ts` to a file called `file.txt` on the file system: ```sh -deno run main.ts > file.tx +deno run main.ts > file.txt ``` To instead redirect _stderr_, use `2>`: ```sh -deno run main.ts 2> file.tx +deno run main.ts 2> file.txt ``` To redirect both stdout _and_ stderr, use `&>`: ```sh -deno run main.ts &> file.tx +deno run main.ts &> file.txt ``` To append to a file, instead of overwriting an existing one, use two right angle brackets instead of one: ```sh -deno run main.ts >> file.tx +deno run main.ts >> file.txt ``` Suppressing either stdout, stderr, or both of a command is possible by @@ -500,7 +500,7 @@ redirecting to `/dev/null`. This works in a cross-platform way including on Windows. ```sh -# suppress stdou +# suppress stdout deno run main.ts > /dev/null # suppress stderr deno run main.ts 2> /dev/null @@ -513,7 +513,7 @@ Or redirecting stdout to stderr and vice-versa: ```sh # redirect stdout to stderr deno run main.ts >&2 -# redirect stderr to stdou +# redirect stderr to stdout deno run main.ts 2>&1 ``` @@ -521,7 +521,7 @@ Input redirects are also supported: ```sh # redirect file.txt to the stdin of gzip -gzip < file.tx +gzip < file.txt ``` Note that redirecting multiple redirects is currently not supported. @@ -550,7 +550,7 @@ Then on a Windows machine: ```sh > pwd -C:\Users\david\dev\my_projec +C:\Users\david\dev\my_project > deno task hi Hello there! ``` @@ -584,7 +584,7 @@ enabled. - **nullglob** - When enabled, globs that don't match any files expand to nothing instead of the literal glob pattern. Enable with `shopt -s nullglob`. - **pipefail** - When enabled, the exit code of a pipeline is the exit code of - the last command to exit with a non-zero status, or zero if all commands exi + the last command to exit with a non-zero status, or zero if all commands exit successfully. Enable with `set -o pipefail`. Examples: @@ -639,7 +639,7 @@ box on Windows, Mac, and Linux. outputs stdin. - [`exit`](https://man7.org/linux/man-pages/man1/exit.1p.html) - Causes the shell to exit. -- [`head`](https://man7.org/linux/man-pages/man1/head.1.html) - Output the firs +- [`head`](https://man7.org/linux/man-pages/man1/head.1.html) - Output the first part of a file. - [`unset`](https://man7.org/linux/man-pages/man1/unset.1p.html) - Unsets environment variables. @@ -655,7 +655,7 @@ Note that if you wish to execute any of these commands in a non-cross-platform way on Mac or Linux, then you may do so by running it through `sh`: `sh -c ` (ex. `sh -c cp source destination`). -## package.json suppor +## package.json support `deno task` falls back to reading from the `"scripts"` entries in a package.json file if it is discovered. Note that Deno does not respect or support any npm @@ -668,17 +668,18 @@ script entries you want to run (ex. When a task command references a binary (e.g., `ohm`, `tsc`, `eslint`), Deno resolves it using the following order: -1. **Workspace `node_modules/.bin/`** - If a `node_modules` directory exists - (from `deno install` or `deno add`), Deno will look for the binary in - `node_modules/.bin/`. This is compatible with how `npx` works in the Node.js - ecosystem. +1. **`node_modules/.bin/`** - If the task's directory or a parent directory has + a `node_modules/.bin/` folder, Deno looks there first. Note that `deno add + npm:` updates `deno.json` imports and `deno.lock` but does **not** + create a `node_modules` directory. The `node_modules` directory is only + created when using `deno install` or other npm-compatible tooling. 2. **Package.json `bin` field** - When a dependency defines a `bin` field in its `package.json`, Deno automatically makes those commands available within task - scripts. This is resolved through Deno's npm compatibility layer. + scripts through its npm compatibility layer. -3. **System PATH** - If the command is not found in `node_modules/.bin/`, Deno - falls back to searching the system PATH. +3. **System PATH** - If the command is not found above, Deno falls back to + searching the system PATH. ### Example From 4fe857f757da90be70983f418aa8e32b67a29e03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bartek=20Iwa=C5=84czuk?= Date: Mon, 25 May 2026 12:54:21 +0200 Subject: [PATCH 7/8] docs(task): drop bold emphasis and fix package.json casing --- runtime/reference/cli/task.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/runtime/reference/cli/task.md b/runtime/reference/cli/task.md index e7af769ba..c6f08ccf1 100644 --- a/runtime/reference/cli/task.md +++ b/runtime/reference/cli/task.md @@ -687,18 +687,18 @@ script entries you want to run (ex. When a task command references a binary (e.g., `ohm`, `tsc`, `eslint`), Deno resolves it using the following order: -1. **`node_modules/.bin/`** - If the task's directory or a parent directory has - a `node_modules/.bin/` folder, Deno looks there first. Note that - `deno add npm:` updates `deno.json` imports and `deno.lock` but does - **not** create a `node_modules` directory. The `node_modules` directory is - only created when using `deno install` or other npm-compatible tooling. +1. `node_modules/.bin/` - if the task's directory or a parent directory has a + `node_modules/.bin/` folder, Deno looks there first. Note that + `deno add npm:` updates `deno.json` imports and `deno.lock` but does not + create a `node_modules` directory. The `node_modules` directory is only + created when using `deno install` or other npm-compatible tooling. -2. **Package.json `bin` field** - When a dependency defines a `bin` field in its +2. `package.json` `bin` field - when a dependency defines a `bin` field in its `package.json`, Deno automatically makes those commands available within task scripts through its npm compatibility layer. -3. **System PATH** - If the command is not found above, Deno falls back to - searching the system PATH. +3. System `PATH` - if the command is not found above, Deno falls back to + searching the system `PATH`. ### Example From d1d5d246d1bf58245733a7d9160dd323ebccec89 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bartek=20Iwa=C5=84czuk?= Date: Mon, 25 May 2026 13:05:26 +0200 Subject: [PATCH 8/8] docs(task): drop npx equivalent section (covered by deno x) --- runtime/reference/cli/task.md | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/runtime/reference/cli/task.md b/runtime/reference/cli/task.md index c6f08ccf1..1f37be128 100644 --- a/runtime/reference/cli/task.md +++ b/runtime/reference/cli/task.md @@ -727,20 +727,3 @@ Running `deno task generate` will: 1. Look for `ohm` in `node_modules/.bin/ohm` 2. If found, execute it using Deno's Node.js compatibility layer 3. The command runs under Deno's runtime, not Node.js. - -### Deno's Equivalent to `npx` - -The equivalent of `npx ` in Deno is: - -```bash -deno run -A npm:@latest -``` - -For example: - -- `npx cowsay hello` -> `deno run -A npm:cowsay@latest hello` -- `npx create-react-app my-app` -> - `deno run -A npm:create-react-app@latest my-app` - -You can also use `deno add npm:` to add an npm dependency and then -reference its binaries in `deno task` scripts.