bun-webview-parallel

Process-isolated Bun.WebView instances for applications that need multiple independent Chrome-backed WebViews at the same time.

Bun's Chrome WebView backend currently shares one Chrome process across WebViews created inside one Bun process, and WebView construction is main-thread-only. bun-webview-parallel uses explicit Bun subprocesses as the concurrency isolation boundary and exposes asynchronous WebView proxies over Bun IPC.

Install

bun add bun-webview-parallel

Basic use

import { createParallelWebViewFactory } from 'bun-webview-parallel'

const factory = createParallelWebViewFactory()

const [a, b] = await Promise.all([
  factory.create({
    backend: { type: 'chrome', url: false },
    dataStore: 'ephemeral',
    headless: true,
  }),
  factory.create({
    backend: { type: 'chrome', url: false },
    dataStore: 'ephemeral',
    headless: true,
  }),
])

console.log(a.hostPid, b.hostPid) // distinct active helper processes

await Promise.all([a.close(), b.close()])
await factory.close()

Optional host pooling

0.0.2 can reuse helper processes between sequential leases:

const factory = createParallelWebViewFactory({
  pool: true,
})

const first = await factory.create(options)
const pid = first.hostPid
await first.close() // reset + release

const second = await factory.create(options)
console.log(second.hostPid === pid) // true when reset/reuse succeeds

Pooling is disabled by default. pool: true uses the basic context-reset policy before a helper is returned to the idle pool. If reset fails, the helper is destroyed rather than reused.

Concurrent leases remain process-isolated: the pool never hands one helper to two active views.

The one-off convenience API createParallelWebView() stays dedicated/process-per-view because there is no retained factory to own idle pooled hosts.

Basic reset scope

The current basic reset clears known-origin browser storage, local/session storage, cookies, HTTP cache, and permissions before reuse. It is intentionally an explicit policy layer rather than pretending to be native Chrome BrowserContext disposal.

See Pooling and context reset for the exact contract and limitations.

Proxy surface

The proxy implements the asynchronous WebView surface needed by browser tooling:

• navigate()
• evaluate()
• cdp()
• click()
• type()
• press()
• resize()
• screenshot()
• addEventListener() / removeEventListener() for CDP events
• close()

Values crossing the process boundary must be structured-cloneable. The package does not attempt to proxy arbitrary native handles or synchronous object identity from the child process.

Isolation contract

Factories expose:

factory.isolation === 'process'
factory.isolatedSessions === true

The package does not schedule test work or decide worker counts. Callers decide concurrency; the package supplies isolated WebView leases.

Tests

bun run test:conformance

The suite covers process isolation, event forwarding, lifecycle, raw same-host reopen, and pooled same-host reuse with context clearing.

See Architecture, Pooling, and Testing.