feat(cli): default to dev command when no subcommand provided

Running `vite` without arguments or with options (e.g., `vite --port 3000`)
now defaults to the dev command, matching the behavior of the upstream
Vite CLI.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: fengmk2

packages/cli/binding/src/lib.rs

@@ -80,7 +80,8 @@ impl From<JsCommandResolvedResult> for ResolveCommandResult {
     }
 }
 
-static BUILTIN_COMMANDS: &[&str] = &["lint", "fmt", "build", "test", "doc", "lib", "preview"];
+static BUILTIN_COMMANDS: &[&str] =
+    &["dev", "lint", "fmt", "build", "test", "doc", "lib", "preview"];
 
 /// Main entry point for the CLI, called from JavaScript.
 ///
@@ -267,30 +268,70 @@ fn js_error_to_resolve_universal_vite_config_error(err: napi::Error) -> Error {
 fn parse_args() -> Args {
     // ArgsOs [node, vite-plus, ...]
     let mut raw_args = std::env::args_os().skip(2);
-    if let Some(first) = raw_args.next()
-        && let Some(first) = first.to_str()
-        && BUILTIN_COMMANDS.contains(&first)
-    {
-        let forwarded_args = raw_args
+
+    // No arguments provided, default to dev command
+    let Some(first) = raw_args.next() else {
+        return Args {
+            task: None,
+            task_args: vec![],
+            commands: Commands::Dev { args: vec![] },
+            debug: false,
+            no_debug: true,
+        };
+    };
+
+    // If first arg is not valid UTF-8, fall through to clap parsing
+    let Some(first_str) = first.to_str() else {
+        return Args::parse_from(std::env::args_os().skip(1));
+    };
+
+    // Collect remaining args for potential forwarding
+    let remaining_args: Vec<_> = raw_args.collect();
+
+    // Handle builtin commands with fast-path parsing (bypasses clap for better arg forwarding)
+    if let Some(cmd) = parse_builtin_command(first_str, &remaining_args) {
+        return cmd;
+    }
+
+    // If first arg starts with '-' but is NOT a help/version flag, treat as options for dev command
+    // e.g. `vite --port 3000` should be treated as `vite dev --port 3000`
+    if first_str.starts_with('-') && !matches!(first_str, "-h" | "--help" | "-V" | "--version") {
+        let forwarded_args: Vec<String> = std::iter::once(first)
+            .chain(remaining_args)
             .map(|a| a.into_string().unwrap_or_else(|os_str| os_str.to_string_lossy().into_owned()))
             .collect();
         return Args {
             task: None,
             task_args: vec![],
-            commands: match first {
-                "lint" => Commands::Lint { args: forwarded_args },
-                "fmt" => Commands::Fmt { args: forwarded_args },
-                "build" => Commands::Build { args: forwarded_args },
-                "test" => Commands::Test { args: forwarded_args },
-                "doc" => Commands::Doc { args: forwarded_args },
-                "lib" => Commands::Lib { args: forwarded_args },
-                "preview" => Commands::Preview { args: forwarded_args },
-                _ => unreachable!(),
-            },
+            commands: Commands::Dev { args: forwarded_args },
             debug: false,
             no_debug: true,
         };
     }
-    // Parse CLI arguments (skip first arg which is the node binary)
+
+    // Fall through to clap parsing for other commands (run, cache, install, help, etc.)
     Args::parse_from(std::env::args_os().skip(1))
 }
+
+fn parse_builtin_command(cmd: &str, raw_args: &[std::ffi::OsString]) -> Option<Args> {
+    if !BUILTIN_COMMANDS.contains(&cmd) {
+        return None;
+    }
+
+    let forwarded_args: Vec<String> =
+        raw_args.iter().map(|a| a.to_string_lossy().into_owned()).collect();
+
+    let commands = match cmd {
+        "dev" => Commands::Dev { args: forwarded_args },
+        "lint" => Commands::Lint { args: forwarded_args },
+        "fmt" => Commands::Fmt { args: forwarded_args },
+        "build" => Commands::Build { args: forwarded_args },
+        "test" => Commands::Test { args: forwarded_args },
+        "doc" => Commands::Doc { args: forwarded_args },
+        "lib" => Commands::Lib { args: forwarded_args },
+        "preview" => Commands::Preview { args: forwarded_args },
+        _ => return None,
+    };
+
+    Some(Args { task: None, task_args: vec![], commands, debug: false, no_debug: true })
+}

packages/cli/snap-tests/command-dev-with-port/snap.txt

@@ -1,2 +1,5 @@
 > vite dev --port 12312312312 2>&1 | grep RangeError # intentionally use an invalid port (exceeds 0-65535) to trigger RangeError
 RangeError [ERR_SOCKET_BAD_PORT]: options.port should be >= 0 and < 65536. Received type number (12312312312).
+
+> vite --port 12312312313 2>&1 | grep RangeError # vite without args should be alias to dev command
+RangeError [ERR_SOCKET_BAD_PORT]: options.port should be >= 0 and < 65536. Received type number (12312312313).

packages/cli/snap-tests/command-dev-with-port/steps.json

@@ -4,6 +4,7 @@
     "VITE_DISABLE_AUTO_INSTALL": "1"
   },
   "commands": [
-    "vite dev --port 12312312312 2>&1 | grep RangeError # intentionally use an invalid port (exceeds 0-65535) to trigger RangeError"
+    "vite dev --port 12312312312 2>&1 | grep RangeError # intentionally use an invalid port (exceeds 0-65535) to trigger RangeError",
+    "vite --port 12312312313 2>&1 | grep RangeError # vite without args should be alias to dev command"
   ]
 }

packages/cli/snap-tests/command-helper/snap.txt

@@ -357,3 +357,41 @@ Options:
   -m, --mode <mode>        [string] set env mode 
   -h, --help               Display this message 
 
+
+> vite dev -h # dev help message
+vite/<semver>
+
+Usage:
+  $ vite [root]
+
+Commands:
+  [root]           start dev server
+  build [root]     build for production
+  optimize [root]  pre-bundle dependencies (deprecated, the pre-bundle process runs automatically and does not need to be called)
+  preview [root]   locally preview production build
+
+For more info, run any command with the `--help` flag:
+  $ vite --help
+  $ vite build --help
+  $ vite optimize --help
+  $ vite preview --help
+
+Options:
+  --host [host]            [string] specify hostname 
+  --port <port>            [number] specify port 
+  --open [path]            [boolean | string] open browser on startup 
+  --cors                   [boolean] enable CORS 
+  --strictPort             [boolean] exit if specified port is already in use 
+  --force                  [boolean] force the optimizer to ignore the cache and re-bundle 
+  --experimentalBundle     [boolean] use experimental full bundle mode (this is highly experimental) 
+  -c, --config <file>      [string] use specified config file 
+  --base <path>            [string] public base path (default: /) 
+  -l, --logLevel <level>   [string] info | warn | error | silent 
+  --clearScreen            [boolean] allow/disable clear screen when logging 
+  --configLoader <loader>  [string] use 'bundle' to bundle the config with Rolldown, or 'runner' (experimental) to process it on the fly, or 'native' (experimental) to load using the native runtime (default: bundle) 
+  -d, --debug [feat]       [string | boolean] show debug logs 
+  -f, --filter <filter>    [string] filter debug logs 
+  -m, --mode <mode>        [string] set env mode 
+  -h, --help               Display this message 
+  -v, --version            Display version number 
+

packages/cli/snap-tests/command-helper/steps.json

@@ -10,6 +10,7 @@
     "vite lint -h # lint help message",
     "vite build -h # build help message",
     "vite test -h # test help message",
-    "vite preview -h # preview help message"
+    "vite preview -h # preview help message",
+    "vite dev -h # dev help message"
   ]
 }