WebContext — Shared Browser Data Profiles

A WebContext is a browser-data profile that controls what cookies, cache, local storage, and IndexedDB data a group of webviews can see. By passing the same context to multiple webviews you make them share a single data store — they behave like tabs in the same browser session. By giving each user or session its own context (pointing to its own directory on disk) you achieve complete isolation between them.

Creating a Context

Always create a WebContext through the application. Calling new WebContext() directly is not supported.

const context = app.createWebContext({
  dataDirectory: './browser-data/user-alice',
  allowsAutomation: false,
});

Creation options

Option	Type	Default	Description
`dataDirectory`	`string`	—	Explicit path to a directory on disk where the browser stores cookies, cache, and databases. Omit this option to let the platform backend choose its default context location.
`allowsAutomation`	`boolean`	`false`	Enable WebDriver automation for this context. See Automation below.

Pass the same WebContext instance to multiple createWebview() calls to give those webviews a common cookie jar, cache, and local storage.

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

// Both windows share the same browser session
const webview1 = windowA.createWebview({
  url: 'https://example.com/dashboard',
  webContext: context,
});

const webview2 = windowB.createWebview({
  url: 'https://example.com/settings',
  webContext: context,
});

// A cookie set in webview1 is immediately visible in webview2
webview1.setCookie({
  name: 'session',
  value: 'abc123',
  domain: 'example.com',
});

Isolated Profiles

Create a separate context for each user or workspace to prevent any data from leaking across profiles:

const aliceCtx = app.createWebContext({
  dataDirectory: './profiles/alice',
});

const bobCtx = app.createWebContext({
  dataDirectory: './profiles/bob',
});

const aliceView = winAlice.createWebview({
  url: 'https://example.com',
  webContext: aliceCtx,
});

const bobView = winBob.createWebview({
  url: 'https://example.com',
  webContext: bobCtx,
});

// Alice and Bob have completely separate cookies, cache, and local storage

Default context (no explicit directory)

Omit dataDirectory to use the platform backend’s default context location. This is not an in-memory guarantee. For a predictable persistent profile, provide an explicit directory; for a private session, use incognito: true on the webview.

const sessionCtx = app.createWebContext();
// equivalent to: app.createWebContext({ dataDirectory: undefined })

const webview = win.createWebview({
  url: 'https://example.com',
  webContext: sessionCtx,
});

Properties and Methods

context.dataDirectory: string | null

The explicitly configured data directory, or null when no directory was passed to the factory. A null value does not mean that the backend uses only memory.

context.isCustomProtocolRegistered(scheme: string): boolean

Returns true if the given URL scheme has been registered as a custom protocol on this context’s native registry.

context.isCustomProtocolRegistered('app'); // true / false

context.setAllowsAutomation(enabled: boolean): void

Enable or disable WebDriver automation support at runtime. See Automation below.

Automation

Setting allowsAutomation: true (or calling context.setAllowsAutomation(true)) enables WebDriver/CDP-based automated testing for webviews that use this context.

Automation is currently enforced only on Linux. The Linux WebKitGTK backend permits at most one automatable context at a time; the backend controls how a conflicting context is reported. Enable automation only for controlled testing environments — never in production builds.

// For integration testing
const testCtx = app.createWebContext({ allowsAutomation: true });

Lifetime and Disposal

Keep a context alive for at least as long as every webview that uses it. Dispose the webviews before disposing their context.

Do not use webviews after disposing their context. Always dispose webviews before their context, or rely on app.exit() to clean everything up in the correct order.

app.exit() disposes all contexts created through that application automatically, in the correct order. For manual cleanup:

// Explicit disposal
context.dispose();
context.isDisposed(); // true

// Or with using declaration
{
  using context = app.createWebContext({ dataDirectory: './session' });
  const webview = win.createWebview({ webContext: context });

  // ... use the webview ...

  webview.dispose();   // dispose webview first
} // context.dispose() called here automatically

Disposal is idempotent — calling dispose() more than once is safe.

Core

UI & System

Types

WebContext — Shared Browser Data Profiles

Creating a Context

Creation options

Isolated Profiles

Default context (no explicit directory)

Properties and Methods

Automation

Lifetime and Disposal

​Creating a Context

​Creation options

​Sharing Data Between Webviews

​Isolated Profiles

​Default context (no explicit directory)

​Properties and Methods

​Automation

​Lifetime and Disposal

Creating a Context

Creation options

Sharing Data Between Webviews

Isolated Profiles

Default context (no explicit directory)

Properties and Methods

Automation

Lifetime and Disposal