WebviewJS Event Loop: Non-Blocking GUI Pump Explained

Every native GUI toolkit needs to drive its own event loop — a tight loop that continuously drains the OS message queue to process redraws, input events, and window signals. Node.js also has its own event loop for async I/O and timers. Traditionally these two loops are incompatible: you can only block on one at a time. WebviewJS solves this by using tao’s non-blocking pump_events() primitive. Instead of handing full control to the native event loop, it drains the OS message queue in a single call that returns immediately, then hands control back to Node. By scheduling that call inside a regular setInterval, both loops run cooperatively on the same thread — the GUI stays responsive and all of Node’s async I/O continues working normally.

How `app.run()` works

app.run() is a small JavaScript wrapper that sets up a setInterval targeting app.pumpEvents() at a configurable interval (default 16 ms, roughly 60 FPS):

// This is the conceptual equivalent of what app.run() does
const timer = setInterval(() => {
  if (!app.pumpEvents()) {
    clearInterval(timer);
  }
}, 16);

pumpEvents() drains all pending OS events without waiting, then returns:

true — the application is still alive; keep pumping.
false — the application should exit; the interval is cleared.

Because the pump runs inside a Node timer, you keep full access to fetch, fs.promises, child_process, WebSockets, and every other Node API while the window is open.

Starting the event loop

You have three ways to start the pump, depending on how much control you need:

import { Application } from '@webviewjs/webview';

const app = new Application();

// Starts the pump automatically and resolves after the first native "resumed" event
await app.whenReady();

const win = app.createBrowserWindow({ title: 'Ready', width: 1024, height: 768 });
win.createWebview({ url: 'https://example.com' });

import { Application } from '@webviewjs/webview';

const app = new Application();

// Start the pump first, then create windows
app.run({ interval: 16, ref: true });

const win = app.createBrowserWindow({ title: 'Manual run', width: 1024, height: 768 });
win.createWebview({ url: 'https://example.com' });

import { Application } from '@webviewjs/webview';

const app = new Application();

const win = app.createBrowserWindow({ title: 'Sync', width: 1024, height: 768 });
win.createWebview({ url: 'https://example.com' });

// Hands control to Tao's native loop; no other JS runs until the app exits
app.runSync();

On macOS, the GUI event loop must run on the main thread — the thread that called new Application(). Do not create Application or BrowserWindow instances from a worker_threads Worker. This is a macOS system requirement enforced by AppKit, not a WebviewJS limitation.

Application readiness

app.whenReady() resolves after tao emits its first native Resumed event, which signals that the application has been granted its window by the OS. Use it as the canonical entry point for creating windows and webviews:

app.whenReady().then(() => {
  const win = app.createBrowserWindow({ title: 'Hello', width: 800, height: 600 });
  win.createWebview({ url: 'https://nodejs.org' });
});

Or with async/await:

await app.whenReady();

const win = app.createBrowserWindow({ title: 'Hello', width: 800, height: 600 });
win.createWebview({ url: 'https://nodejs.org' });

Pass an options object to configure the pump that whenReady() starts internally:

await app.whenReady({
  interval: 16,  // milliseconds between pumps (default: 16)
  ref: true,     // keep the process alive while the timer is running (default: true)
});

To wait for readiness without starting the pump automatically — for example, when you want to call app.run() yourself with different options — set autoRun: false:

const ready = app.whenReady({ autoRun: false });

// Start your own pump with custom settings
app.run({ interval: 33, ref: false });

// Await the readiness signal separately
await ready;

app.whenReady() is the idiomatic entry point for WebviewJS applications. It handles pump startup, readiness detection, and async/await integration in a single call. Prefer it over calling app.run() manually unless you need fine-grained control over the timer.

Controlling pump frequency

The interval and ref options let you trade responsiveness for CPU usage:

Option	Type	Default	Description
`interval`	`number`	`16`	Milliseconds between `pumpEvents()` calls. 16 ms ≈ 60 FPS.
`ref`	`boolean`	`true`	When `false`, the timer is `unref()`’d — the process can exit naturally even while the pump is running.

// 30 FPS — friendlier to battery and CPU for simple or mostly-idle UIs
app.run({ interval: 33 });

// Unref'd timer — the process exits when all other async work finishes,
// regardless of whether the GUI is still open
app.run({ interval: 16, ref: false });

// Combine with whenReady for a 30 FPS unref'd pump
await app.whenReady({ interval: 33, ref: false });

Stopping the application

Two methods stop the event pump, with different levels of finality:

// Stop the interval but leave all windows open and native resources intact.
// You can restart pumping manually with app.run() afterwards.
app.stop();

// Stop the pump AND hide all windows AND mark the application as exited.
// Retained BrowserWindow / Webview wrappers subsequently report isDisposed() === true.
app.exit();

stop() without exit() is useful when you want to take over the loop yourself temporarily:

app.stop();

// Drive a tight custom loop — for example, a CPU-intensive rendering burst
while (framesToProcess-- > 0) {
  app.pumpEvents();
}

// Hand control back to the interval-based pump
app.run();

Handling graceful shutdown

Listen for application-close-requested to run cleanup code before the process exits:

app.on('application-close-requested', () => {
  console.log('All windows closed — cleaning up.');
  // flush logs, save state, etc.
  app.exit();
});

Without calling app.exit() in this handler, the pump timer keeps the process alive even after the last window is closed.

Get Started

Guides

Platform Notes

WebviewJS Event Loop: Non-Blocking GUI Pump Explained

How `app.run()` works

Starting the event loop

Application readiness

Controlling pump frequency

Stopping the application

Handling graceful shutdown

​How app.run() works

​Starting the event loop

​Application readiness

​Controlling pump frequency

​Stopping the application

​Handling graceful shutdown

How `app.run()` works

Starting the event loop

Application readiness

Controlling pump frequency

Stopping the application

Handling graceful shutdown