Introduction
Native OS webview windows for Bun and Node.js
What is native-window?
native-window lets you create real desktop windows with embedded web content from Bun or Node.js. It uses platform-native webview engines — WKWebView on macOS 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 three packages:
| Package | Description |
|---|---|
@fcannizzaro/native-window | Rust napi-rs addon that provides native window and webview APIs |
@fcannizzaro/native-window-ipc | Pure TypeScript typed IPC channel layer (optional, zero runtime dependencies) |
@fcannizzaro/native-window-ipc-react | React hooks for typed IPC in webview apps (optional, wraps the IPC client) |
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, or use the React hooks package if your webview app is built with React.
Platform Support
| Platform | Webview Engine | Status |
|---|---|---|
| macOS (ARM, x64) | WKWebView | Always available (system framework) |
| Windows (x64, ARM) | WebView2 | Pre-installed on Windows 11; auto-installable on Windows 10 via ensureRuntime() |
| Linux | — | Not supported |
How It Works
The native addon uses a command queue architecture. 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.