> ## 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.

# Installing WebviewJS: Node.js, Deno, and Bun Setup

> Install @webviewjs/webview via npm, configure platform prerequisites, and verify your setup. Covers Windows, macOS, and Linux requirements.

This page walks you through installing `@webviewjs/webview`, satisfying the platform-level system dependencies, and verifying that your environment can open a native window. If you need to compile the Rust extension yourself, see [Building from source](#building-from-source) at the bottom.

<Warning>
  WebviewJS requires **Node.js 24 or later**. Earlier versions of Node.js are not supported because the prebuilt native binaries target the NAPI version shipped with Node 24. Run `node --version` to confirm before continuing.
</Warning>

## Prerequisites

Each operating system needs a native webview runtime and, on Linux, a few additional libraries. Check the tab for your platform before you install the npm package.

<Tabs>
  <Tab title="Windows">
    WebviewJS uses the **WebView2** runtime that ships with every modern version of Windows:

    * **Windows 11** — WebView2 is built in; no action needed.
    * **Windows 10** — WebView2 is automatically installed alongside Microsoft Edge. If Edge is absent on a corporate machine, download the [Evergreen Bootstrapper](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) from Microsoft.

    No additional packages are required. The prebuilt `.node` binary for your architecture (`x64`, `x86`, or `arm64`) is downloaded automatically by npm.
  </Tab>

  <Tab title="macOS">
    WebviewJS uses the **WebKit** engine built into macOS. No additional installation is needed.

    * Minimum supported version: **macOS 10.15 Catalina**
    * Both Intel (`x64`) and Apple Silicon (`arm64`) are supported with separate prebuilt binaries.

    Make sure your Xcode Command Line Tools are up to date if you plan to build from source:

    ```bash theme={null}
    xcode-select --install
    ```
  </Tab>

  <Tab title="Linux">
    WebviewJS uses **WebKitGTK** on Linux. You must install it plus `libxdo` before the native module can load.

    <CodeGroup>
      ```bash apt (Debian / Ubuntu) theme={null}
      sudo apt install libwebkit2gtk-4.1-dev libxdo-dev
      ```

      ```bash dnf (Fedora / RHEL) theme={null}
      sudo dnf install webkit2gtk4.1-devel libxdo-devel
      ```

      ```bash pacman (Arch Linux) theme={null}
      sudo pacman -S webkit2gtk-4.1 xdotool
      ```
    </CodeGroup>

    WebviewJS works with both **X11** and **Wayland**. On Wayland compositors, set `WEBKIT_DISABLE_COMPOSITING_MODE=1` if you see rendering artefacts.
  </Tab>
</Tabs>

## Install the package

Once the system prerequisites are in place, install `@webviewjs/webview` from npm. The postinstall script downloads the prebuilt binary that matches your platform and architecture automatically.

<CodeGroup>
  ```bash npm theme={null}
  npm install @webviewjs/webview
  ```

  ```bash yarn theme={null}
  yarn add @webviewjs/webview
  ```

  ```bash pnpm theme={null}
  pnpm add @webviewjs/webview
  ```

  ```bash bun theme={null}
  bun add @webviewjs/webview
  ```
</CodeGroup>

## Verify your installation

Create a small test file to confirm that the native module loads and can open a window:

```js verify.mjs theme={null}
import { Application } from '@webviewjs/webview';

const app = new Application();

app.whenReady().then(() => {
  const win = app.createBrowserWindow({
    title: 'WebviewJS works!',
    width: 800,
    height: 600,
  });

  win.createWebview({ html: '<h1>Hello from WebviewJS 👋</h1>' });
});
```

Run it with:

```bash theme={null}
node verify.mjs
```

A native window containing the heading should appear. Close it to exit. If the process starts but no window appears, double-check your [platform prerequisites](#prerequisites).

## Building from source

Building from source requires the **Rust stable toolchain** and **Bun** in addition to the system dependencies above. Use this path when:

* You are targeting a platform or architecture without a prebuilt binary.
* You need to apply a local patch to the Rust extension.
* You are contributing to the project itself.

```bash theme={null}
# 1. Clone the repository
git clone https://github.com/webviewjs/webview
cd webview

# 2. Install JavaScript dependencies
bun install

# 3. Compile the Rust extension and generate JS bindings
bun run build
```

The compiled `.node` file is placed in a platform-specific subdirectory (for example, `win32-x64-msvc/` or `linux-x64-gnu/`) and `index.js` is updated automatically to load it. You can then use the local build directly by pointing your project's dependency at the cloned folder.