Issue Review: cloudflare/workers-sdk#5469

Summary

Feature request to add a warning about -- command and --proxy options in wrangler pages dev not working correctly on PowerShell.

Findings

• Created: 2024-04-02
• Updated: 2025-10-30
• Version: "All Wranglers" -> 4.60.0
• Component: Pages (wrangler pages dev)
• Labels: bug, pages, error-messaging
• Comments: 0

Key Evidence

1. Referenced Issue #965: The issue references GitHub issue #965, which describes the original bug where wrangler pages dev -- npm run serve fails on PowerShell but works on Command Prompt.

2. Issue #965 Already Fixed: The changelog shows issue #965 was fixed in wrangler 2.0.5+ by making the command argument variadic:

   On Windows, the following command wrangler pages dev -- foo bar would error saying that bar was not a known argument. This is because foo and bar are passed to Yargs as separate arguments. A workaround is to put the command in quotes: wrangler pages dev -- "foo bar". But this fix makes the command argument variadic, which also solves the problem.

3. Current Code Analysis: Reviewing packages/wrangler/src/pages/dev.ts:

   • The -- <command> and --proxy options are already deprecated with a clear warning (line 1045):

     Specifying a `-- <command>` or `--proxy` is deprecated and will be removed in a future version of Wrangler.
     Build your application to a directory and run the `wrangler pages dev <directory>` instead.
     This results in a more faithful emulation of production behavior.
     

   • The code uses shell: isWindows() when spawning the proxy process (line 1070), which helps with some Windows-specific issues.
   • There is no specific PowerShell warning implemented.

4. Context from Issue #965 Comments:

   • petebacondarwin (maintainer) wrote: "This is a known issue on a Pages command that we have deprecated. I think it would be nice to try to tell if you are trying to do this in PowerShell and add a warning. I'll open an issue to add that."
   • This issue (#5469) was created as a result of that comment.

5. Feature is Deprecated: Since the -- command and --proxy features are already deprecated and slated for removal, adding a PowerShell-specific warning has questionable value:

   • The deprecation warning already advises users to migrate away from this pattern
   • Any investment in PowerShell detection would be for a deprecated feature

Recommendation

Status: CLOSE

Reasoning: The underlying bug (#965) was fixed in wrangler 2.0.5. Additionally, the -- command and --proxy features are now deprecated with clear warnings advising users to use wrangler pages dev <directory> instead. Adding a PowerShell-specific warning for a deprecated feature that's slated for removal provides minimal value and would require non-trivial effort to detect the shell environment reliably.

Action: Close with comment explaining the status.

Suggested Comment

Thank you for opening this issue. After review:

1. The original underlying bug (#965) was fixed in wrangler 2.0.5 by making the command argument variadic, which resolves the PowerShell argument parsing issue for most cases.

2. The -- <command> and --proxy options have since been deprecated and will be removed in a future version of Wrangler. The current deprecation warning already advises users to migrate to wrangler pages dev <directory> instead.

Given that the feature is deprecated with a clear migration path and the original parsing issue was addressed, we're closing this issue. If you encounter specific issues with the deprecated command pattern, the recommended workaround is to quote the command: wrangler pages dev -- "npm run serve", or preferably migrate to the non-deprecated approach of building to a directory first.