DioxusLabs / DioxusLabs/dioxus

feat(desktop): expose Config::with_background_throttling to opt out of WKWebView WebContent suspension

Open
#5,586 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
39.1k
Forks
1.9k
Avg merge
4d 10h
Merged PRs (30d)
4

Description

## Summary

`dioxus-desktop` builds on `wry`, which has supported `WebView::with_background_throttling(BackgroundThrottlingPolicy)` for a while now, but the policy is not surfaced through `dioxus_desktop::Config`. There is currently no way for a Dioxus desktop app to opt out of macOS WKWebView's default WebContent-process throttling — and on a headless host (CI, hidden window, no focus) that throttling indefinitely suspends every JS timer, fetch, and event handler running in the page.

## Motivation

We hit this building [`@wdio/dioxus-service`](https://github.com/webdriverio/desktop-mobile), a WebdriverIO service for automated testing of Dioxus desktop apps. Our embedded-WebDriver mode runs an Axum HTTP server inside the app process and dispatches `executeScript` requests to the webview through a JS polling loop. On macOS-ARM GitHub-Actions runners — no display, no user input, app window not visible — WKWebView's WebContent process gets suspended within seconds of launch, freezing the polling loop. The same test suite passes on Linux/Windows CI and on macOS interactively.

`caffeinate`, `NSAppSleepDisabled=YES`, JS-side workarounds (silent `AudioContext`, muted `HTMLAudioElement`) all failed because the throttling is **WebKit-internal** (not OS-level App Nap). The only fix that worked was calling `WebViewBuilder::with_background_throttling(BackgroundThrottlingPolicy::Disabled)` at WebView construction, which is exactly what wry exposes already.

Beyond automation, this also matters for any Dioxus desktop app that needs to do background work in the webview: long-running renderers, background music/streaming UIs, background data sync, system-tray apps with a hidden main window, etc.

## Proposed API

```rust
use dioxus::desktop::wry::BackgroundThrottlingPolicy;

let config = dioxus::desktop::Config::new()
.with_background_throttling(BackgroundThrottlingPolicy::Disabled);
```

Three variants from wry:

- `Disabled` — never throttle.
- `Suspend` — fully suspend tasks when the view isn't in a window (current implicit default).
- `Throttle` — limit rather than suspend.

The setting applies at WebView creation. On non-Apple platforms wry currently ignores the attribute, so this is effectively a macOS-only opt-out.

## Implementation

PR is up at #5587 with the change against `main`. Cross-referencing here so the discussion thread stays in one place.

## Related

- wry: https://docs.rs/wry/latest/wry/struct.WebViewBuilder.html#method.with_background_throttling
- WebKit docs on background tab throttling: https://developer.apple.com/documentation/webkit/wkwebpagepreferences/4111121-inactiveschedulingpolicy

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.