Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/webviewjs/webview/llms.txt

Use this file to discover all available pages before exploring further.

WebContext owns the browser-data layer — cookies, disk cache, local storage, and IndexedDB — used by the webviews associated with it. By sharing a single context across multiple webviews you give them a common session (useful for keeping a user logged in across panels). By creating separate contexts you achieve hard profile isolation, as if each context were an independent browser profile. The Application owns all contexts it creates, but you can also dispose them early when a profile is no longer needed.
Never call new WebContext() directly — it is not supported and will not behave correctly. Always create contexts through app.createWebContext(options).

​
Creation

const context = app.createWebContext(options?: WebContextOptions): WebContext
​
options
WebContextOptions
​
returns
WebContext
A new WebContext instance owned by the application.
import { resolve } from 'node:path';
import { Application } from '@webviewjs/webview';

const app = new Application();

// Persistent context — data survives across restarts.
const context = app.createWebContext({
  dataDirectory: resolve('./.browser-profile'),
});

console.log('Profile at:', context.dataDirectory);

​
Properties

​
dataDirectory

context.dataDirectory: string | null
The data directory path configured at creation time, or null if no directory was provided (in-memory context).

​
Methods

​
isCustomProtocolRegistered(scheme)

context.isCustomProtocolRegistered(scheme: string): boolean
Check whether a custom URL scheme has been registered on this context’s native protocol registry.
​
scheme
string
required
The scheme name to query (e.g. 'app', 'custom').
​
returns
boolean
true if the scheme is registered, false otherwise.

​
setAllowsAutomation(flag)

context.setAllowsAutomation(flag: boolean): void
Enable or disable WebDriver automation on this context at runtime.
​
flag
boolean
required
true to enable automation, false to disable.
This setting is currently only enforced on Linux. Only one WebContext per application may have automation enabled at a time. Attempting to enable it on a second context while another has it active will throw.

​
dispose()

context.dispose(): void
Release the native context immediately. All webviews that were using this context will lose their shared data store — ensure no webviews are actively using the context before disposing it.

​
isDisposed()

context.isDisposed(): boolean
Returns true if the context has been disposed (either explicitly or via app.exit()).

​
Symbol.dispose

WebContext implements the TC39 Explicit Resource Management protocol: 
{
  using context = app.createWebContext({ dataDirectory: './profile' });
  // … create webviews, do work …
} // context.dispose() called automatically

​
Sharing a Context Across Webviews

Pass the same context instance to multiple createWebview() calls. All webviews sharing the context will use the same cookie store, cache, and storage — logging in on one webview makes that session available in the other. 
import { resolve } from 'node:path';
import { Application } from '@webviewjs/webview';

const app = new Application();

const context = app.createWebContext({
  dataDirectory: resolve('./.webviewjs-example-profile'),
});

const firstWindow = app.createBrowserWindow({
  title: 'Shared context: window one',
  width: 700,
  height: 500,
});

const secondWindow = app.createBrowserWindow({
  title: 'Shared context: window two',
  width: 700,
  height: 500,
  x: 740,
  y: 80,
});

// Both webviews share the same session.
const _first = firstWindow.createWebview({
  url: 'https://example.com',
  webContext: context,
});

const _second = secondWindow.createWebview({
  url: 'https://example.com',
  webContext: context,
});

console.log('Shared data directory:', context.dataDirectory);

app.on('application-close-requested', () => app.exit());
app.run();

​
Profile Isolation

Create a separate context for each isolated profile. Webviews in different contexts have entirely separate cookie jars, caches, and storage — useful for multi-account UIs or sandboxed content: 
const profileA = app.createWebContext({ dataDirectory: './profile-a' });
const profileB = app.createWebContext({ dataDirectory: './profile-b' });

const winA = app.createBrowserWindow({ title: 'Profile A', width: 800, height: 600 });
const winB = app.createBrowserWindow({ title: 'Profile B', width: 800, height: 600, x: 850 });

// Each webview has its own independent session.
winA.createWebview({ url: 'https://example.com', webContext: profileA });
winB.createWebview({ url: 'https://example.com', webContext: profileB });

// No dataDirectory — all data is lost when the context is disposed.
const ephemeral = app.createWebContext();

win.createWebview({
  url: 'https://example.com',
  webContext: ephemeral,
});
A webview created without a webContext option uses a private default context. Pass an explicit WebContext whenever you need to share state or control the data directory.

​
Lifecycle Notes

  • Keep the WebContext alive for at least as long as every webview that uses it. Disposing a context while webviews are still referencing it results in undefined behaviour.
  • app.exit() automatically disposes every context created through that application.
  • Disposal is idempotent — calling dispose() more than once is safe.

Build docs developers (and LLMs) love

Get started for freeTalk to us