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

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 at the bottom.

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.

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.

Windows
macOS
Linux

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 from Microsoft.

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

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:

xcode-select --install

WebviewJS uses WebKitGTK on Linux. You must install it plus libxdo before the native module can load.

sudo apt install libwebkit2gtk-4.1-dev libxdo-dev

sudo dnf install webkit2gtk4.1-devel libxdo-devel

sudo pacman -S webkit2gtk-4.1 xdotool

WebviewJS works with both X11 and Wayland. On Wayland compositors, set WEBKIT_DISABLE_COMPOSITING_MODE=1 if you see rendering artefacts.

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.

npm install @webviewjs/webview

yarn add @webviewjs/webview

pnpm add @webviewjs/webview

bun add @webviewjs/webview

Verify your installation

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

verify.mjs

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:

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.

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.

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

Get Started

Guides

Platform Notes

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

Prerequisites

Install the package

Verify your installation

Building from source

​Prerequisites

​Install the package

​Verify your installation

​Building from source

Prerequisites

Install the package

Verify your installation

Building from source