Introduction

What is native-window?

native-window lets you create real desktop windows with embedded web content from Bun, Deno or Node.js. It uses wry and tao under the hood — providing WebKit on macOS and Linux, and WebView2 on Windows — so there is no bundled Chromium or Electron runtime. The result is a lightweight, fast way to build desktop UIs with web technologies.

The project is split into four packages:

You can use the core package alone for raw window management and message passing, add the IPC package for compile-time checked, type-safe communication between your host process and the webview, use the React hooks package if your webview app is built with React, or add the TanStack DB adapter to sync host-side data to reactive collections in the webview.

Key Capabilities

• Native webviews — powered by wry + tao (WebKit on macOS/Linux, WebView2 on Windows), no Electron or Chromium bundled
• Multi-window — create and manage multiple independent windows
• Bidirectional IPC — send messages between Bun/Deno/Node.js and the webview
• Typesafe IPC channels — typed message layer with schema-based validation and compile-time checked event maps
• Security hardening — URL scheme blocking, CSP injection, trusted origin filtering, webview surface hardening, IPC bridge hardening, message size limits, and rate limiting
• Cookie access — read (including HttpOnly) and clear cookies from the native cookie store
• DevTools control — programmatically open, close, and query the browser devtools panel
• Incognito mode — ephemeral sessions with no persistent storage (cookies, cache, local storage)
• Window icons — set per-window icons from PNG or ICO files (Windows and Linux)
• Runtime detection — check for WebView2 availability and auto-install on Windows

Platform Support

How It Works

The native addon uses tao for cross-platform windowing and wry for webview management, with a command queue architecture on top. When you call methods like setTitle() or loadHtml(), commands are enqueued and then drained on the main thread by pumpEvents(), which also pumps the OS event loop to keep windows responsive.

The NativeWindow class manages this lifecycle automatically — it initializes the native subsystem on first window creation, starts pumping events at ~60fps, and stops when all windows are closed. You don't need to call init() or pumpEvents() manually.

Next Steps