> ## Documentation Index
> Fetch the complete documentation index at: https://webview.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# WebContext — Shared Browser Data Profiles

> Use WebContext to share cookies, cache, and storage across webviews, or isolate browser data in separate persistent profiles per user or session.

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.

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

### Creation options

| Option             | Type      | Default | Description                                                                                                                                                                     |
| ------------------ | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dataDirectory`    | `string`  | —       | Path to a directory on disk where the browser stores cookies, cache, and databases. Omit this option for an in-memory (ephemeral) context that is wiped when the process exits. |
| `allowsAutomation` | `boolean` | `false` | Enable WebDriver automation for this context. See [Automation](#automation) below.                                                                                              |

***

## Sharing Data Between Webviews

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

```ts theme={null}
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:

```ts theme={null}
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
```

***

## In-Memory (Ephemeral) Context

Omit `dataDirectory` to create a context that lives only in RAM. All browser data is discarded when the context is disposed or the process exits. This is the right choice for temporary sessions, guest modes, or anything that must not leave traces on disk.

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

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

***

## Properties and Methods

```ts theme={null}
context.dataDirectory: string | null
```

The configured persistent data directory, or `null` for an in-memory context.

***

```ts theme={null}
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.

```ts theme={null}
context.isCustomProtocolRegistered('app'); // true / false
```

***

```ts theme={null}
context.setAllowsAutomation(enabled: boolean): void
```

Enable or disable WebDriver automation support at runtime. See [Automation](#automation) below.

***

## Automation

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

<Warning>
  Automation is currently **enforced only on Linux**. On Linux, only **one context at a time** can have automation enabled. Attempting to enable it on a second context while another is already enabled will throw. Enable automation only for controlled testing environments — never in production builds.
</Warning>

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

***

## Lifetime and Disposal

You must keep a context alive for **at least as long as every webview that uses it**. If you dispose a context while webviews still hold a reference to it, those webviews will encounter errors.

<Warning>
  Disposing a `WebContext` while webviews are still using it leads to undefined behavior. Always dispose webviews before their context, or rely on `app.exit()` to clean everything up in the correct order.
</Warning>

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

```ts theme={null}
// 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.