WebviewJS Quickstart: Build Your First Desktop Window

In this guide you’ll install WebviewJS, open a native OS window, load content into it, react to window events, and send a message from the page back to Node.js. By the end you’ll have a working desktop app and an understanding of the core building blocks — Application, BrowserWindow, and Webview.

Install WebviewJS

Add the package to your project:

npm install @webviewjs/webview

Make sure you have Node.js 24 or later and that your platform dependencies are satisfied. See the Installation guide for per-platform setup instructions.

Create your first window

Create a file called app.mjs and add the following:

app.mjs

import { Application } from '@webviewjs/webview';

const app = new Application();

// Keep the wrappers available for later method calls and event listeners
let mainWindow = null;
let mainWebview = null;

app.whenReady().then(() => {
  mainWindow = app.createBrowserWindow({
    title: 'My First WebviewJS App',
    width: 1024,
    height: 768,
  });

  mainWebview = mainWindow.createWebview({
    url: 'https://example.com',
  });
});

Run it:

node app.mjs

A native window opens and loads https://example.com. Close the window to exit.

Keep BrowserWindow and Webview wrappers in variables for as long as you need to call their methods or use their event listeners. The application owns the native resources, so garbage-collecting a wrapper does not itself dispose the native object.

Load local HTML

Instead of navigating to a URL, pass an html string to render content directly without a web server:

mainWebview = mainWindow.createWebview({
  html: `<!DOCTYPE html>
<html lang="en">
  <head><meta charset="UTF-8"><title>Hello</title></head>
  <body>
    <h1>Hello from WebviewJS!</h1>
    <p>Running on Node.js ${process.version}</p>
  </body>
</html>`,
});

Use the html option for self-contained pages, prototypes, or any scenario where you want to serve content without a protocol handler or HTTP server.

Handle window events

The Application instance is a typed EventEmitter. Listen for lifecycle events to react to user actions:

app.whenReady().then(() => {
  mainWindow = app.createBrowserWindow({ title: 'My App', width: 1024, height: 768 });
  mainWebview = mainWindow.createWebview({ url: 'https://example.com' });

  // Fires when an OS close request removes the last tracked window
  app.on('application-close-requested', () => {
    console.log('All windows closed — exiting.');
    app.exit();
  });

  // Fires when the OS delivers a close request for a window
  app.on('window-close-requested', () => {
    console.log('A window close was requested.');
  });
});

The runtime shuts down automatically after the OS close request for the last tracked window. Calling app.exit() in this handler is safe and idempotent, but it is not required to stop the pump.

Add IPC — page to Node

The page can send messages to your Node.js code using window.ipc.postMessage(). Listen with webview.onIpcMessage():

app.whenReady().then(() => {
  mainWindow = app.createBrowserWindow({ title: 'IPC Demo', width: 800, height: 600 });

  mainWebview = mainWindow.createWebview({
    html: `<!DOCTYPE html>
<html>
  <body>
    <h1 id="status">Waiting…</h1>
    <button onclick="window.ipc.postMessage('ping')">Send ping</button>
  </body>
</html>`,
  });

  mainWebview.onIpcMessage((msg) => {
    const text = msg.body.toString('utf-8');
    console.log('Received from page:', text); // "ping"

    // Send a reply back into the page
    mainWebview.evaluateScript(
      `document.getElementById('status').textContent = 'Node replied: pong'`
    );
  });
});

Click the button in the window — “ping” appears in your terminal and the page updates to show “Node replied: pong”.

Going further: expose async functions

For a cleaner request/response pattern, use webview.expose() to publish an entire namespace of Node.js functions directly to the page. Every exposed function automatically becomes a Promise in the browser context:

import { Application } from '@webviewjs/webview';
import { readFile } from 'node:fs/promises';

const app = new Application();
let mainWindow = null;
let mainWebview = null;

app.whenReady().then(() => {
  mainWindow = app.createBrowserWindow({ title: 'Expose Demo', width: 800, height: 600 });

  mainWebview = mainWindow.createWebview({
    html: `<!DOCTYPE html>
<html>
  <body>
    <pre id="out">Loading config…</pre>
    <script>
      window.native.readConfig().then(cfg => {
        document.getElementById('out').textContent = JSON.stringify(cfg, null, 2);
      });
    </script>
  </body>
</html>`,
  });

  // Expose a namespace called "native" to the page
  mainWebview.expose('native', {
    version: '1.0.0',
    readConfig: async () => JSON.parse(await readFile('./config.json', 'utf-8')),
  });
});

Static exposed values, function arguments, and function return values must be JSON-serializable. Violations throw a SerializationError.

Event Loop

Understand how the non-blocking pump works and how to control it.

IPC Messaging

Deep-dive into page ↔ Node communication patterns.

API Reference — Application

Full reference for the Application class, events, and options.

Build Executables

Compile your app into a standalone executable.

Get Started

Guides

Platform Notes

WebviewJS Quickstart: Build Your First Desktop Window

Going further: expose async functions

Event Loop

IPC Messaging

API Reference — Application

Build Executables

​Going further: expose async functions

Event Loop

IPC Messaging

API Reference — Application

Build Executables

Going further: expose async functions