DioxusLabs / DioxusLabs/dioxus
feat(desktop): expose Config::with_background_throttling to opt out of WKWebView WebContent suspension
- 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.