fix: dev frontend readiness

[savely-krasovsky]

Description

This PR prevents wails3 dev from terminating the native application when the frontend development server takes longer than expected to start.

Previously, frontend readiness was checked inside application.App.Run using 10 HTTP attempts with 500 ms delays. This gave the frontend approximately five seconds to become available.

Frontend startup can legitimately take longer when Vite needs to optimize or re-optimize dependencies. In that case, Wails terminated the native application with a fatal error even
though the frontend server was still starting normally:

$ vite -- --port 9245 --strictPort
1:47PM INF Retrying...
1:47PM INF Retrying...
1:47PM INF Retrying...
[vite] Forced re-optimization of dependencies
[vite] Re-optimizing dependencies because lockfile has changed
1:47PM INF Retrying...
1:47PM ERR
******************************** FATAL *********************************
*      There has been a catastrophic failure in your application.     *
**************************** Error Details *****************************
unable to connect to frontend server. Please check it is running -
FRONTEND_DEVSERVER_URL='http://localhost:9245'
************************************************************************
ERROR task: Failed to run task "run": exit status 1

This PR moves frontend readiness from the application runtime into the wails3 dev process orchestration:

• The frontend development server starts as a background process.
• A one-shot readiness step waits for the frontend port to accept connections.
• The native application starts as the primary process only after the readiness check succeeds.
• The default startup timeout is increased to 60 seconds.
• A new wails3 tool waitport command provides the readiness check.
• Frontend startup policy is removed from application.App.Run.
• Generated development configuration includes the required task ordering.
• Tests cover the port retry logic and generated configuration.

This prevents valid but slow frontend startups from terminating the application and keeps development-process coordination out of the application runtime.

Migration for existing Wails v3 alpha projects

Existing projects must update their generated development configuration manually.

Add the following task to build/Taskfile.yml, next to the existing dev:frontend task:

  dev:wait:
    summary: Waits for the frontend development server
    vars:
      TIMEOUT: 60
    cmds:
      - wails3 tool waitport --timeout {{.TIMEOUT}}

Then update dev_mode.executes in build/config.yml by inserting the readiness step after the background frontend task and before the primary application task:

dev_mode:
  executes:
    - cmd: wails3 build DEV=true
      type: blocking
    - cmd: wails3 task common:dev:frontend
      type: background
    - cmd: wails3 task common:dev:wait
      type: once
    - cmd: wails3 task run
      type: primary

The important execution order is:

build (blocking) → frontend (background) → readiness (once) → app (primary)

Projects using a custom wails3 dev -config file must update that configuration instead of build/config.yml.

Projects whose frontend server does not use WAILS_VITE_PORT may specify the host and port explicitly:

  dev:wait:
    cmds:
      - wails3 tool waitport -h 127.0.0.1 -p 5173 --timeout 60

Newly generated projects include the updated configuration automatically.

Dependency

This PR temporarily depends on the fix/background-startup-exit branch of github.com/savely-krasovsky/refresh. That branch adds the background and one-shot process semantics required for startup orchestration.

The current development replacement is:

replace github.com/atterpac/refresh => ../../refresh

Before this PR can be merged, the refresh changes must be published or merged and the local replacement must be changed to an upstream version or remote pseudo-version.

Fixes #?

Type of change

Please select the option that is relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Unit tests were added for:

• Retrying the port check until the frontend becomes available.
• Returning immediately when retries are disabled.
• The generated development-process ordering.
• The background frontend process preceding the readiness check.
• The one-shot readiness check preceding the primary application.
• The default 60-second frontend startup timeout.
• Existing watcher ignore-list behaviour.

Manual verification procedure:

1. Build and install wails3 from this branch with the required refresh changes.
2. Update an existing project using the migration instructions above.
3. Ensure the frontend dependencies require optimization, or otherwise introduce a startup delay.
4. Run wails3 dev
5. Verify that the frontend development server starts as a background process.
6. Verify that the readiness task waits while the frontend is starting.
7. Verify that the native application starts only after the frontend port accepts connections.
8. Verify that no fatal frontend-readiness error or initial asset proxy error is emitted.
9. Stop or prevent the frontend server from starting and verify that startup fails after the configured timeout without launching the native application.

• Windows
• macOS
• Linux

If you checked Linux, please specify the distro and version.

Tested on Fedora Linux 44 using a Toolbx container.

Test Configuration

OS: Fedora Linux 44 (Toolbx Container Image)
Architecture: linux/amd64
Go: 1.26.5
Wails: v3.0.0-dev
GTK: 4.22.4
WebKitGTK: 2.52.5

Checklist:

• (v2 only) I have updated website/src/pages/changelog.mdx with details of this PR (v3 changelog entries are added automatically)
• My code follows the general coding style of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Summary by CodeRabbit

• New Features
  • Added a waitport development tool that blocks until a specified host/port becomes reachable, with a configurable timeout (default: 60s).
  • Updated wails3 dev startup so the native app launches only after the frontend dev server is accepting connections, including alpha-project flow.
• Documentation
  • Updated the unreleased changelog with explicit alpha-project startup ordering steps.
• Tests
  • Added coverage for port readiness/timeout behavior and development startup sequencing.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

The CLI adds wails3 tool waitport, development assets wait for frontend readiness before launching the native application, and application lifecycle hooks are simplified. Tests cover polling, configuration ordering, timeout behavior, and assertion semantics.

Changes

Frontend readiness startup

Layer / File(s)	Summary
Port readiness command and polling v3/internal/commands/tool_waitport.go, v3/internal/commands/tool_waitport_test.go, v3/cmd/wails3/main.go	Adds configurable host, port, and timeout handling, readiness polling, timeout errors, tests, and CLI wiring for waitport.
Development startup readiness gate v3/internal/commands/build_assets/*, v3/internal/commands/dev_config_test.go, v3/UNRELEASED_CHANGELOG.md	Adds the dev:wait task and inserts the readiness command into development execution ordering, with configuration tests and changelog documentation.
Application lifecycle alignment v3/pkg/application/application.go, v3/pkg/application/application_dev.go, v3/pkg/application/application_production.go, v3/go.mod, v3/internal/commands/watcher_test.go	Removes the pre-run hook, adjusts MCP startup placement, updates development and production quit handling, upgrades the refresh module, and changes watcher assertions to fail immediately.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant DevTask
  participant FrontendDevServer
  participant WailsCLI
  participant NativeApplication
  DevTask->>FrontendDevServer: Start frontend development server
  DevTask->>WailsCLI: Run wails3 tool waitport
  WailsCLI->>FrontendDevServer: Poll configured port
  FrontendDevServer-->>WailsCLI: Accept connection
  WailsCLI-->>DevTask: Complete readiness task
  DevTask->>NativeApplication: Start native application

Loading

Possibly related PRs

• wailsapp/wails#5776: Covers the same frontend development server startup ordering and readiness-wait changes.
• wailsapp/wails#5526: Also updates the github.com/atterpac/refresh module version.
• wailsapp/wails#5126: Introduces the Taskfile templating delimiters used by the readiness command.

Suggested reviewers: leaanthony

Poem

I’m a rabbit by the waiting port,
Guarding startup’s eager court.
When frontend lights begin to glow,
The native app may safely go.
Hop, hop—no race today!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and clearly summarizes the main change: frontend readiness handling for dev startup.
Description check	✅ Passed	The description mostly follows the template with a clear summary, testing details, environment info, and checklist coverage.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@v3/go.mod`:
- Around line 5-6: Remove the local sibling replacement for
github.com/atterpac/refresh in go.mod and pin it to a compatible tracked module
revision instead. Ensure clean checkouts and CI can resolve the imported refresh
packages without requiring ../../refresh to exist.

In `@v3/internal/commands/tool_waitport.go`:
- Around line 46-60: Update the port-resolution logic in the wait-port command
to reject values outside 1..65535, including environment-derived ports, before
invoking waitForPort. Validate the command timeout is positive before
constructing the duration or polling, and return clear validation errors for
invalid values. Add command-level tests covering invalid flag and environment
ports, plus zero and negative timeouts.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: e22fe157-59f9-4675-901a-5db12f03bd0f

📥 Commits

Reviewing files that changed from the base of the PR and between 94c4a8d and 008a368.

📒 Files selected for processing (12)

• v3/UNRELEASED_CHANGELOG.md
• v3/cmd/wails3/main.go
• v3/go.mod
• v3/internal/commands/build_assets/Taskfile.tmpl.yml
• v3/internal/commands/build_assets/config.yml
• v3/internal/commands/dev_config_test.go
• v3/internal/commands/tool_waitport.go
• v3/internal/commands/tool_waitport_test.go
• v3/internal/commands/watcher_test.go
• v3/pkg/application/application.go
• v3/pkg/application/application_dev.go
• v3/pkg/application/application_production.go