docs: clarify environment variable prefixes in task commands by Tarte12 · Pull Request #3161 · voidzero-dev/vite-plus

Tarte12 · 2026-10-21T06:02:20Z

Note that Vite Task parses simple commands and && chains itself, so they behave the same on every platform.
Document that FOO=bar command works on Windows without cross-env.
Clarify that a prefix applies only to the command it directly precedes.
Note that && chains are split into cached sub-tasks only when they don't use other shell syntax.
Fix the command reference, which implied every command runs through a shell.

Shell fallback details are intentionally left out, per the discussion above.

Verified on Windows 11 with vite-plus 1.4.0: prefixes work in simple commands and && chains and apply only to the next command. With a pipe, the prefix fails under cmd.exe and the && chain is not split into sub-tasks.

hyunbinseo · 2026-10-21T09:02:04Z

After reviewing, I think Vite Task should document how it parses commands first, so these docs can link to it instead of describing internals. This goes beyond env prefixes: it decides cross-platform behavior and whether && chains become cached sub-tasks.

I'll open a vite-task issue to spec it alongside task-cache.md.

jong-kyung · 2026-10-21T10:34:55Z

cc @wan9chi

hyunbinseo · 2026-10-21T11:07:13Z


+### Environment Variable Prefixes
+
+Vite Task parses simple commands and `&&` chains itself, including environment variable prefixes such as `FOO=bar command`. These work on every platform, including Windows, without `cross-env`:


Shouldn't the Vite Task parsing be placed on the top of vpr docs (e.g. as a note block)?

I don't think this explanation applies to "Environment Variable Prefixes" only.

Moved to an info block at the top of the page.

hyunbinseo · 2026-10-21T11:08:04Z

+```json [package.json]
+{
+  "scripts": {
+    "build": "NODE_ENV=production vp build"


Why not use a vanilla non-vp command inside the build script?

Switched to node build.js.

hyunbinseo · 2026-10-21T11:09:50Z

+A prefix applies only to the command it precedes. In `FOO=1 a && b`, `FOO` is set for `a` but not for `b`.
+
+If any part of a command uses other shell syntax, such as pipes, redirects, or variable expansion, the whole command runs in the system shell instead: `/bin/sh -c` on macOS and Linux, and `cmd.exe /d /s /c` on Windows. In that case, `FOO=bar command` does not work on Windows, so use `cross-env` there.


These seem to be implementation details. It would be nice if Vite Task had documentation of these that can be linked to? Or at least it should be converted to a warning block, etc.

Dropped the shell details and the Vite Task link per the discussion, and replaced them with a short warning that points to cross-env.

hyunbinseo · 2026-10-21T11:14:24Z

 - **Type:** `string | string[]`

-Defines the shell command to run for the task. The string is interpreted by a shell, so spaces, quoting, `&&`, pipes, and redirects all work as written on the command line.
+Defines the command to run for the task. Quoting, `&&`, pipes, and redirects all work as written on the command line. Vite Task runs simple commands and `&&` chains directly, and falls back to the system shell for other shell syntax. See [Environment Variable Prefixes](/guide/run#environment-variable-prefixes) for details.


"Work as written" isn't true on Windows when it falls back to cmd.exe (e.g. single quotes, $VAR). Same as the guide, it'd be nice to link to Vite Task docs for the parsing rules. Until then, how about:

Suggested change

Defines the command to run for the task. Quoting, `&&`, pipes, and redirects all work as written on the command line. Vite Task runs simple commands and `&&` chains directly, and falls back to the system shell for other shell syntax. See [Environment Variable Prefixes](/guide/run#environment-variable-prefixes) for details.

Defines the command to run for the task. Vite Task parses simple commands and `&&` chains itself, so they behave the same on every platform. Other shell syntax, such as pipes and redirects, runs in the system shell: `/bin/sh` on macOS and Linux, and `cmd.exe` on Windows. See [Environment Variable Prefixes](/guide/run#environment-variable-prefixes) for details.

Applied your suggestion without the /bin/sh / cmd.exe part to keep internals out. Verified on Windows; see the updated PR description.

hyunbinseo · 2026-10-21T11:14:26Z

 - **Type:** `string | string[]`

-Defines the shell command to run for the task. The string is interpreted by a shell, so spaces, quoting, `&&`, pipes, and redirects all work as written on the command line.
+Defines the command to run for the task. Quoting, `&&`, pipes, and redirects all work as written on the command line. Vite Task runs simple commands and `&&` chains directly, and falls back to the system shell for other shell syntax. See [Environment Variable Prefixes](/guide/run#environment-variable-prefixes) for details.


Line 120 is now inconsistent: && is only split into cached sub-tasks when parsed, not on shell fallback. Array entries are always split. Maybe update it too?

Updated line 120, and the matching sentence in Compound Commands in the guide.

hyunbinseo · 2026-10-23T03:22:25Z

@jong-kyung How should we proceed? I would love to out-link Vite Task behaviors as mentioned above. The PR can be polished for review once it is decided.

jong-kyung · 2026-10-23T03:30:14Z

Personally, I think it would be better not to link to the Vite Task docs

hyunbinseo · 2026-10-23T03:38:58Z

Thanks for the quick reply. We'll drop the detailed Vite Task behavior and keep the PR focused on:

Simple commands are parsed by Vite+ (Vite Task) directly.
One benefit: FOO=bar command works on Windows without cross-env.
A prefix applies only to the command it directly precedes. The docs will also note that other behaviors (e.g. shell fallback) exist and should be verified at runtime.

- Move the note that Vite Task parses simple commands to the top of the run guide - Use a non-`vp` command in the env prefix example - Replace shell fallback internals with a short warning that points to `cross-env` - Reword the `command` reference and the `&&` sub-task notes to match

hyunbinseo

Consistency. Reuse a single well phrased Vite Task explanation. (e.g. in a blockquote form)
Generalization. The vanilla Vite docs does mention dotenv-expand but it's purely because its codes are used. Here, Vite Task handles it by itself. cross-env and Windows can be mentioned as an example but it can be shortened and generalized.

hyunbinseo · 2026-10-25T03:39:44Z

 - **Type:** `string | string[]`

-Defines the shell command to run for the task. The string is interpreted by a shell, so spaces, quoting, `&&`, pipes, and redirects all work as written on the command line.
+Defines the command to run for the task. Vite Task parses simple commands and `&&` chains itself, so they behave the same on every platform. Other shell syntax, such as pipes and redirects, may behave differently across platforms. See [Environment Variable Prefixes](/guide/run#environment-variable-prefixes) for details.


Why not drop [Environment Variable Prefixes] hyperlink? It only illustrates a single example.

hyunbinseo · 2026-10-25T03:40:49Z

 Each task defined in `vite.config.ts` must include its own `command`. You cannot define a task in both `vite.config.ts` and `package.json` with the same task name.

-Commands joined with `&&` (or supplied as an array) are automatically split into independently cached sub-tasks. See [Compound Commands](/guide/run#compound-commands).
+Array entries, and `&&` chains without other shell syntax, are automatically split into independently cached sub-tasks. See [Compound Commands](/guide/run#compound-commands).


Inconsistent hyperlink with what guide/run.md uses this. What is the correct one?

[`&&` chains](#compound-commands)

Kept the existing See [Compound Commands] link and removed the inline one.

hyunbinseo · 2026-10-25T03:43:25Z

 `vpr` is available as a standalone shorthand for `vp run`. All examples below work with both `vp run` and `vpr`.
 :::

+::: info


Why not make it identical to config/run.md? So similar yet different in few words.

Also, can't we use the same block syntax in that file as well? Seems much cleaner.

Defines the command to run for the task. ::: info ...

hyunbinseo · 2026-10-25T03:44:50Z


+### Environment Variable Prefixes
+
+Because Vite Task parses simple commands itself, environment variable prefixes such as `FOO=bar command` work on every platform, including Windows, without `cross-env`:


cross-env is a third party package. Can we emphasize that it's an example?

Changed to "extra tools like cross-env".

hyunbinseo · 2026-10-25T03:45:10Z

+A prefix applies only to the command it directly precedes. In `FOO=1 a && b`, `FOO` is set for `a` but not for `b`.
+
+::: warning
+If a command also uses other shell syntax, such as pipes or redirects, environment variable prefixes may not work on Windows. Verify such commands at runtime, and use `cross-env` if needed.


Why not tighten and make it more general.

Shortened to one line.

Tarte12 · 2026-10-25T04:15:59Z

Thanks! Moved the explanation into a shared info block and generalized the prefix section.

docs: document env prefixes in task commands

eb279a1

Tarte12 changed the title ~~docs: document env prefixes in task commands~~ docs: clarify environment variable prefixes in task commands Oct 21, 2026

hyunbinseo suggested changes Oct 21, 2026

View reviewed changes

hyunbinseo suggested changes Oct 25, 2026

View reviewed changes

docs: share Vite Task info block and generalize env prefix section

fa35ba3

Tarte12 marked this pull request as ready for review October 25, 2026 05:04

liangmiQwQ requested a review from wan9chi October 25, 2026 10:38


		### Environment Variable Prefixes

		Vite Task parses simple commands and `&&` chains itself, including environment variable prefixes such as `FOO=bar command`. These work on every platform, including Windows, without `cross-env`:

		A prefix applies only to the command it precedes. In `FOO=1 a && b`, `FOO` is set for `a` but not for `b`.

		If any part of a command uses other shell syntax, such as pipes, redirects, or variable expansion, the whole command runs in the system shell instead: `/bin/sh -c` on macOS and Linux, and `cmd.exe /d /s /c` on Windows. In that case, `FOO=bar command` does not work on Windows, so use `cross-env` there.

	Defines the command to run for the task. Quoting, `&&`, pipes, and redirects all work as written on the command line. Vite Task runs simple commands and `&&` chains directly, and falls back to the system shell for other shell syntax. See [Environment Variable Prefixes](/guide/run#environment-variable-prefixes) for details.
	Defines the command to run for the task. Vite Task parses simple commands and `&&` chains itself, so they behave the same on every platform. Other shell syntax, such as pipes and redirects, runs in the system shell: `/bin/sh` on macOS and Linux, and `cmd.exe` on Windows. See [Environment Variable Prefixes](/guide/run#environment-variable-prefixes) for details.


		### Environment Variable Prefixes

		Because Vite Task parses simple commands itself, environment variable prefixes such as `FOO=bar command` work on every platform, including Windows, without `cross-env`:

Conversation

Tarte12 commented Oct 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hyunbinseo commented Oct 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jong-kyung commented Oct 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hyunbinseo commented Oct 23, 2026

Uh oh!

jong-kyung commented Oct 23, 2026

Uh oh!

hyunbinseo commented Oct 23, 2026

Uh oh!

hyunbinseo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Tarte12 commented Oct 25, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Tarte12 commented Oct 21, 2026 •

edited

Loading

hyunbinseo commented Oct 21, 2026 •

edited

Loading