Application — WebviewJS Root Object and Event Loop

Application is the root of a WebviewJS program. It owns the native event loop, all BrowserWindow instances, tray icons, web contexts, and menus you create through it. Create an application before using its factory methods and keep it alive for the duration of the resources you use.

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

const app = new Application();

Constructor

new Application(options?: ApplicationOptions)

ApplicationOptions is accepted by the constructor but is currently unused. You can safely pass null or omit the argument entirely.

Lifecycle Methods

`run(options?)`

Starts the event pump by calling pumpEvents() on a setInterval and returns immediately, leaving the Node.js event loop free for async work such as file I/O and timers. This is the recommended way to drive the event loop in most Node.js applications.

app.run(options?: { interval?: number; ref?: boolean }): void

number

default:"16"

How often to pump OS events, in milliseconds. The default of 16 ms targets ~60 FPS.

boolean

default:"true"

When false, the underlying timer is unref’d and will not prevent the Node.js process from exiting on its own.

`runSync()`

Runs the native Tao event loop on the current thread and blocks JavaScript until the application exits. The Node.js event loop is unavailable while this call is in progress.

app.runSync(): void

Use run() in most Node.js applications. Reserve runSync() for cases where you explicitly want the GUI loop to own the thread.

`stop()`

Clears the pump interval started by run(). The Application object and all windows remain valid — you can restart the pump by calling run() again.

app.stop(): void

`exit()`

Stops the pump, hides all tracked windows, and marks the application as exited. Subsequent pumpEvents() calls return false. All resources owned by the application (windows, webviews, tray icons, web contexts) are disposed.

app.exit(): void

`pumpEvents()`

Processes one batch of OS events without blocking. Returns true while the application is alive, false when the application should stop. You normally do not call this directly — run() drives it automatically.

app.pumpEvents(): boolean

`whenReady(options?)`

Returns a Promise that resolves after the first pumpEvents() call marks the application ready. By default, calling whenReady() also starts the event pump automatically.

app.whenReady(options?: ApplicationWhenReadyOptions): Promise<void>

type ApplicationWhenReadyOptions =
  | { autoRun?: true; interval?: number; ref?: boolean }
  | { autoRun: false; interval?: never; ref?: never };

boolean

default:"true"

When true (default), whenReady() calls run() internally. Set to false when you plan to drive the loop manually with run() or pumpEvents().

number

Forwarded to run(). Only valid when autoRun is true.

boolean

Forwarded to run(). Only valid when autoRun is true.

If the application is already ready when you call whenReady(), the promise still resolves asynchronously on the next microtask tick.

`isReady()`

Returns true after the first pumpEvents() or runSync() call has marked the application ready.

app.isReady(): boolean

Factory Methods

Use these methods to create WebviewJS resources. Resources created through the application are automatically tracked and disposed when app.exit() is called.

`createBrowserWindow(options?)`

Creates and returns a new BrowserWindow wrapping an OS-level window.

app.createBrowserWindow(options?: BrowserWindowOptions): BrowserWindow

See BrowserWindow for the full options reference.

`createChildBrowserWindow(options?)`

Creates a BrowserWindow flagged as a child (isChild === true). This method does not accept a parent window or establish a native parent/owner relationship. Use child: true and explicit bounds on a webview when you need a view positioned inside its host window.

app.createChildBrowserWindow(options?: BrowserWindowOptions): BrowserWindow

`createWebContext(options?)`

Creates an isolated browser-data context that can be shared across multiple webviews, giving them a common cookie jar, cache, and local storage.

app.createWebContext(options?: WebContextOptions): WebContext

Always create contexts through app.createWebContext(). Calling new WebContext() directly is not supported.

See WebContext for the full API reference.

`createTrayIcon(options)`

Creates a system tray icon with an optional menu and tooltip.

app.createTrayIcon(options: TrayIconOptions): TrayIcon

`setMenu(options?)`

Sets the global application menu. On Windows and Linux, set it before creating windows so those windows receive it. Calling it later does not reattach the replacement menu to existing windows. On macOS it updates the application-level menu. Pass null or omit the argument to remove the non-macOS global menu; macOS restores its default application menu. Android ignores menu configuration.

app.setMenu(options?: MenuOptions | null): void

See the Menus guide for the full MenuOptions shape.

Application Events

Application extends the standard Node.js EventEmitter. Subscribe to application-level events with .on(), .once(), or any other EventEmitter method.

Event reference

Event	Payload	Fired when
`ready`	`ApplicationEvent`	The first `pumpEvents()` or `runSync()` call marks the application ready
`window-close-requested`	`ApplicationEvent`	The OS delivers a close request for a tracked window
`application-close-requested`	`ApplicationEvent`	An OS close request removes the last tracked window; shutdown follows immediately
`custom-menu-click`	`ApplicationEvent` (`customMenuEvent.id`, `customMenuEvent.windowId`)	A custom menu item is selected

The ApplicationEvent payload shape:

interface ApplicationEvent {
  event: string; // "ready", "window-close-requested", "application-close-requested", or "custom-menu-click"
  customMenuEvent?: {
    id: string;       // the menu item's id string
    windowId: number; // currently emitted as 0; not a reliable source-window identifier
  };
}

customMenuEvent is present for custom-menu-click. The current native implementation sets windowId to 0 rather than the originating window’s ID, so do not use it to route a click to a particular window.

Usage example

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

const app = new Application();

app.on('ready', () => {
  console.log('Native event loop is ready');
});

app.on('window-close-requested', () => {
  console.log('A window close was requested');
});

app.on('application-close-requested', () => {
  // The runtime is already shutting down after the last tracked window closes.
  app.exit();
});

app.on('custom-menu-click', ({ customMenuEvent }) => {
  if (customMenuEvent) {
    console.log(`Menu item "${customMenuEvent.id}" clicked`);
  }
});

await app.whenReady();

Available EventEmitter methods

Method	Description
`on(event, listener)`	Add a persistent listener
`once(event, listener)`	Add a one-time listener
`off(event, listener)`	Alias for `removeListener`
`addListener(event, listener)`	Add a persistent listener (alias for `on`)
`removeListener(event, listener)`	Remove a specific listener
`removeAllListeners(event?)`	Remove all listeners for an event, or all events
`listenerCount(event)`	Number of listeners for an event
`listeners(event)`	Copy of the listener array for an event
`rawListeners(event)`	Listener array including once-wrappers
`emit(event, payload)`	Synchronously invoke all listeners
`eventNames()`	Array of registered event names

All registration and removal methods return this and are chainable.

Legacy `onEvent()` / `bind()`

These methods are provided for backwards compatibility. Prefer the EventEmitter API (.on(), .once(), etc.) for new code.

app.onEvent(handler: (event: ApplicationEvent) => void): void
app.bind(handler: (event: ApplicationEvent) => void): void

The exported WebviewApplicationEvent enum is retained for compatibility, but the event field delivered by the current API is a string. Compare it with the event names directly:

app.onEvent((event) => {
  if (event.event === 'application-close-requested') {
    app.exit();
  }
  if (event.event === 'custom-menu-click') {
    console.log(event.customMenuEvent?.id);
  }
});

`WebviewApplicationEvent` value	Fired when
`WindowCloseRequested`	The OS delivered a close request for a tracked window
`ApplicationCloseRequested`	An OS close request removed the last tracked window
`CustomMenuClick`	A custom menu item was clicked
`Ready`	The first event-pump call marked the application ready

Resource Management

`Symbol.dispose`

Application implements the TC39 Explicit Resource Management protocol. You can use a using declaration to guarantee cleanup even if an exception is thrown:

{
  using app = new Application();
  // ... your application code ...
} // app.exit() is called automatically here

Root-owned disposal

Every resource you create through an Application instance — windows, webviews, tray icons, web contexts, and menus — is owned by that application. Calling app.exit() (or triggering [Symbol.dispose]) disposes all of them in one shot. Disposal is idempotent: calling exit() more than once is safe. After disposal, retained resource wrapper objects (e.g. BrowserWindow, Webview) report isDisposed() === true and throw if you call further methods on them. Attempting to create new resources after exit() also throws.

app.exit();
// All owned resources (windows, webviews, tray icons, web contexts) are now disposed.

Complete Example

The following example shows the recommended pattern for a WebviewJS application using whenReady():

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

const app = new Application();

// Handle menu clicks
app.on('custom-menu-click', ({ customMenuEvent }) => {
  if (customMenuEvent?.id === 'quit') {
    app.exit();
  }
});

// The runtime shuts down after the last tracked window close request.
// Calling exit() here is optional but safe.
app.on('application-close-requested', () => {
  app.exit();
});

// whenReady() starts the event pump and resolves once the platform is ready
await app.whenReady();

const win = app.createBrowserWindow({
  title: 'My App',
  width: 1280,
  height: 720,
});

win.createWebview({ url: 'https://example.com' });

Core

UI & System

Types

Application — WebviewJS Root Object and Event Loop

Constructor

Lifecycle Methods

`run(options?)`

`runSync()`

`stop()`

`exit()`

`pumpEvents()`

`whenReady(options?)`

`isReady()`

Factory Methods

`createBrowserWindow(options?)`

`createChildBrowserWindow(options?)`

`createWebContext(options?)`

`createTrayIcon(options)`

`setMenu(options?)`

Application Events

Event reference

Usage example

Available EventEmitter methods

Legacy `onEvent()` / `bind()`

Resource Management

`Symbol.dispose`

Root-owned disposal

Complete Example

​Constructor

​Lifecycle Methods

​run(options?)

​runSync()

​stop()

​exit()

​pumpEvents()

​whenReady(options?)

​isReady()

​Factory Methods

​createBrowserWindow(options?)

​createChildBrowserWindow(options?)

​createWebContext(options?)

​createTrayIcon(options)

​setMenu(options?)

​Application Events

​Event reference

​Usage example

​Available EventEmitter methods

​Legacy onEvent() / bind()

​Resource Management

​Symbol.dispose

​Root-owned disposal

​Complete Example

Constructor

Lifecycle Methods

`run(options?)`

`runSync()`

`stop()`

`exit()`

`pumpEvents()`

`whenReady(options?)`

`isReady()`

Factory Methods

`createBrowserWindow(options?)`

`createChildBrowserWindow(options?)`

`createWebContext(options?)`

`createTrayIcon(options)`

`setMenu(options?)`

Application Events

Event reference

Usage example

Available EventEmitter methods

Legacy `onEvent()` / `bind()`

Resource Management

`Symbol.dispose`

Root-owned disposal

Complete Example