feat: Make Vite server timeout configurable (#4374)

leaanthony · claude · web-flow · commit 1ec3708f68f5 · 2025-07-11T21:08:37.000+10:00
* feat: Make Vite server timeout configurable - Add ViteServerTimeout field to wails.json configuration (default: 10 seconds) - Add --viteservertimeout CLI flag for dev command - Update error message to be more descriptive about timeout duration - Fix issue #4372 where slow Vite servers with SvelteKit/Tailwind exceeded 10s timeout Users can now configure the timeout via: 1. wails.json: "viteServerTimeout": 30 2. CLI flag: wails dev --viteservertimeout 30 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: Add documentation for viteServerTimeout configuration - Document viteServerTimeout field in wails.json project config - Add --viteservertimeout CLI flag documentation - Update save flag description to include new option 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * Update changelog --------- Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/v2/cmd/wails/flags/dev.go b/v2/cmd/wails/flags/dev.go
@@ -31,6 +31,7 @@ type Dev struct {
 	AppArgs              string `flag:"appargs" description:"arguments to pass to the underlying app (quoted and space separated)"`
 	Save                 bool   `flag:"save" description:"Save the given flags as defaults"`
 	FrontendDevServerURL string `flag:"frontenddevserverurl" description:"The url of the external frontend dev server to use"`
+	ViteServerTimeout    int    `flag:"viteservertimeout" description:"The timeout in seconds for Vite server detection (default: 10)"`
 
 	// Internal state
 	devServerURL  *url.URL
@@ -105,6 +106,13 @@ func (d *Dev) loadAndMergeProjectConfig() error {
 
 	d.AppArgs, _ = lo.Coalesce(d.AppArgs, d.projectConfig.AppArgs)
 
+	if d.ViteServerTimeout == 0 && d.projectConfig.ViteServerTimeout != 0 {
+		d.ViteServerTimeout = d.projectConfig.ViteServerTimeout
+	} else if d.ViteServerTimeout == 0 {
+		d.ViteServerTimeout = 10 // Default timeout
+	}
+	d.projectConfig.ViteServerTimeout = d.ViteServerTimeout
+
 	if d.Save {
 		err = d.projectConfig.Save()
 		if err != nil {
diff --git a/v2/cmd/wails/internal/dev/dev.go b/v2/cmd/wails/internal/dev/dev.go
@@ -99,7 +99,7 @@ func Application(f *flags.Dev, logger *clilogger.CLILogger) error {
 	// frontend:dev:watcher command.
 	frontendDevAutoDiscovery := projectConfig.IsFrontendDevServerURLAutoDiscovery()
 	if command := projectConfig.DevWatcherCommand; command != "" {
-		closer, devServerURL, devServerViteVersion, err := runFrontendDevWatcherCommand(projectConfig.GetFrontendDir(), command, frontendDevAutoDiscovery)
+		closer, devServerURL, devServerViteVersion, err := runFrontendDevWatcherCommand(projectConfig.GetFrontendDir(), command, frontendDevAutoDiscovery, projectConfig.ViteServerTimeout)
 		if err != nil {
 			return err
 		}
@@ -205,7 +205,7 @@ func runCommand(dir string, exitOnError bool, command string, args ...string) er
 }
 
 // runFrontendDevWatcherCommand will run the `frontend:dev:watcher` command if it was given, ex- `npm run dev`
-func runFrontendDevWatcherCommand(frontendDirectory string, devCommand string, discoverViteServerURL bool) (func(), string, string, error) {
+func runFrontendDevWatcherCommand(frontendDirectory string, devCommand string, discoverViteServerURL bool, viteServerTimeout int) (func(), string, string, error) {
 	ctx, cancel := context.WithCancel(context.Background())
 	scanner := NewStdoutScanner()
 	cmdSlice := strings.Split(devCommand, " ")
@@ -225,9 +225,9 @@ func runFrontendDevWatcherCommand(frontendDirectory string, devCommand string, d
 		select {
 		case serverURL := <-scanner.ViteServerURLChan:
 			viteServerURL = serverURL
-		case <-time.After(time.Second * 10):
+		case <-time.After(time.Second * time.Duration(viteServerTimeout)):
 			cancel()
-			return nil, "", "", errors.New("failed to find Vite server URL")
+			return nil, "", "", fmt.Errorf("failed to find Vite server URL: Timed out waiting for Vite to output a URL after %d seconds", viteServerTimeout)
 		}
 	}
 
diff --git a/v2/internal/project/project.go b/v2/internal/project/project.go
@@ -93,6 +93,9 @@ type Project struct {
 	// Frontend directory
 	FrontendDir string `json:"frontend:dir"`
 
+	// The timeout in seconds for Vite server detection. Default 10
+	ViteServerTimeout int `json:"viteServerTimeout"`
+
 	Bindings Bindings `json:"bindings"`
 }
 
@@ -175,6 +178,9 @@ func (p *Project) setDefaults() {
 	if p.DevServer == "" {
 		p.DevServer = "localhost:34115"
 	}
+	if p.ViteServerTimeout == 0 {
+		p.ViteServerTimeout = 10
+	}
 	if p.NSISType == "" {
 		p.NSISType = "multiple"
 	}
diff --git a/website/docs/reference/cli.mdx b/website/docs/reference/cli.mdx
@@ -194,6 +194,7 @@ Your system is ready for Wails development!
 | -extensions                  | Extensions to trigger rebuilds (comma separated)                                                                                                                                    | go                    |
 | -forcebuild                  | Force build of application                                                                                                                                                          |                       |
 | -frontenddevserverurl "url"  | Use 3rd party dev server url to serve assets, EG Vite                                                                                                                               | ""                    |
+| -viteservertimeout           | The timeout in seconds for Vite server detection when frontend dev server url is set to 'auto'                                                                                      | 10                    |
 | -ldflags "flags"             | Additional ldflags to pass to the compiler                                                                                                                                          |                       |
 | -loglevel "loglevel"         | Loglevel to use - Trace, Debug, Info, Warning, Error                                                                                                                                | Debug                 |
 | -nocolour                    | Turn off colour cli output                                                                                                                                                          | false                 |
@@ -202,7 +203,7 @@ Your system is ready for Wails development!
 | -race                        | Build with Go's race detector                                                                                                                                                       | false                 |
 | -reloaddirs                  | Additional directories to trigger reloads (comma separated)                                                                                                                         | Value in `wails.json` |
 | -s                           | Skip building the frontend                                                                                                                                                          | false                 |
-| -save                        | Saves the given `assetdir`, `reloaddirs`, `wailsjsdir`, `debounce`, `devserver` and `frontenddevserverurl` flags in `wails.json` to become the defaults for subsequent invocations. |                       |
+| -save                        | Saves the given `assetdir`, `reloaddirs`, `wailsjsdir`, `debounce`, `devserver`, `frontenddevserverurl` and `viteservertimeout` flags in `wails.json` to become the defaults for subsequent invocations. |                       |
 | -skipbindings                | Skip bindings generation                                                                                                                                                            |                       |
 | -skipembedcreate             | Skip automatic creation of non-existent embed directories and gitkeep files                                                                                                         |                       |
 | -tags "extra tags"           | Build tags to pass to compiler (quoted and space separated)                                                                                                                         |                       |
diff --git a/website/docs/reference/project-config.mdx b/website/docs/reference/project-config.mdx
@@ -34,6 +34,8 @@ The project config resides in the `wails.json` file in the project directory. Th
   "frontend:dev:watcher": "",
   // URL to a 3rd party dev server to be used to serve assets, EG Vite. \nIf this is set to 'auto' then the devServerUrl will be inferred from the Vite output
   "frontend:dev:serverUrl": "",
+  // The timeout in seconds for Vite server detection when frontend:dev:serverUrl is set to 'auto'. Default: 10
+  "viteServerTimeout": 10,
   // Relative path to the directory that the auto-generated JS modules will be created
   "wailsjsdir": "",
   // The name of the binary
@@ -124,7 +126,7 @@ The project config resides in the `wails.json` file in the project directory. Th
 
 This file is read by the Wails CLI when running `wails build` or `wails dev`.
 
-The `assetdir`, `reloaddirs`, `wailsjsdir`, `debounceMS`, `devserver` and `frontenddevserverurl` flags in `wails build/dev` will update the project config
+The `assetdir`, `reloaddirs`, `wailsjsdir`, `debounceMS`, `devserver`, `frontenddevserverurl` and `viteservertimeout` flags in `wails build/dev` will update the project config
 and thus become defaults for subsequent runs.
 
 The JSON Schema for this file is located [here](https://wails.io/schemas/config.v2.json).
diff --git a/website/src/pages/changelog.mdx b/website/src/pages/changelog.mdx
@@ -14,6 +14,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Configure Vite timeout by @leaanthony in [PR](https://github.com/wailsapp/wails/pull/4374)
+
 ## v2.10.2 - 2025-07-06
 
 ### Fixed

Original file line number	Diff line number	Diff line change
`@@ -93,6 +93,9 @@ type Project struct {`
`93`	`93`	`// Frontend directory`
`94`	`94`	FrontendDir string `json:"frontend:dir"`
`95`	`95`
	`96`	`+ // The timeout in seconds for Vite server detection. Default 10`
	`97`	+ ViteServerTimeout int `json:"viteServerTimeout"`
	`98`	`+`
`96`	`99`	Bindings Bindings `json:"bindings"`
`97`	`100`	`}`
`98`	`101`
`@@ -175,6 +178,9 @@ func (p *Project) setDefaults() {`
`175`	`178`	`if p.DevServer == "" {`
`176`	`179`	`p.DevServer = "localhost:34115"`
`177`	`180`	`}`
	`181`	`+ if p.ViteServerTimeout == 0 {`
	`182`	`+ p.ViteServerTimeout = 10`
	`183`	`+ }`
`178`	`184`	`if p.NSISType == "" {`
`179`	`185`	`p.NSISType = "multiple"`
`180`	`186`	`}`