Skip to content

webview

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

webview

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
scripts
scripts
 
 
src
src
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
package.json
package.json
 
 
tsconfig.json
tsconfig.json
 
 

README.md

@rcompat/webview

Native webview for JavaScript runtimes.

What is @rcompat/webview?

A cross-runtime module for creating native desktop applications with web technologies. Uses the system's native webview (WebKit on macOS/Linux, WebView2 on Windows) for lightweight, fast rendering. Works with Bun and Deno.

Note: Node.js bindings will be added at a later date.

Installation

npm install @rcompat/webview
pnpm add @rcompat/webview
yarn add @rcompat/webview
bun add @rcompat/webview

Usage

Basic webview

import platform from "@rcompat/webview/default";
import Webview from "@rcompat/webview";

const webview = new Webview({ platform });

webview.navigate("https://example.com");
webview.run();

Set HTML content directly

import platform from "@rcompat/webview/default";
import Webview from "@rcompat/webview";

const webview = new Webview({ platform });

webview.html = `
  <!DOCTYPE html>
  <html>
    <body>
      <h1>Hello from Webview!</h1>
    </body>
  </html>
`;

webview.run();

Custom window size

import platform from "@rcompat/webview/default";
import Webview from "@rcompat/webview";

const webview = new Webview({ platform });

webview.size = {
    width: 800,
    height: 600,
    hint: 0, // 0=none, 1=min, 2=max, 3=fixed
};

webview.navigate("https://example.com");
webview.run();

Debug mode

import platform from "@rcompat/webview/default";
import Webview from "@rcompat/webview";

// enable developer tools
const webview = new Webview({ platform, debug: true });

webview.navigate("https://example.com");
webview.run();

Server with webview in worker

Create a local server and open it in a webview using a worker for non-blocking operation:

worker.ts

import platform from "@rcompat/webview/default";
import Webview from "@rcompat/webview";

const webview = new Webview({ platform });

webview.navigate("http://localhost:8181");
webview.run();

app.ts

import serve from "@rcompat/http/serve";

const headers = { "Content-Type": "text/html" };
const html = `
  <html>
    <body>
      <h1>Desktop App</h1>
      <a href="https://github.com">GitHub</a>
    </body>
  </html>
`;

serve(() => new Response(html, { headers }), { port: 8181 });

// Bun
new Worker("worker.ts");

// Deno
new Worker(new URL("worker.ts", import.meta.url).href, { type: "module" });

API Reference

Webview

import Webview from "@rcompat/webview";

new Webview(init: Init);

Constructor Options

Property Type Default Description
platform BunFile — Platform binary (required)
debug boolean false Enable developer tools

Properties

Property Type Description
html string (set) Set HTML content directly
size Size (set) Set window dimensions

Size Object

Property Type Default Description
width number 1280 Window width in pixels
height number 720 Window height in pixels
hint 0-3 0 0=none, 1=min, 2=max, 3=fixed

Methods

Method Description
navigate(url) Navigate to a URL
run() Start the webview event loop (blocking)
destroy() Terminate and clean up the webview

Platform Exports

// auto-detect current platform
import platform from "@rcompat/webview/default";

// or specify explicitly
import platform from "@rcompat/webview/darwin-arm64"; // macOS ARM
import platform from "@rcompat/webview/darwin-x64"; // macOS Intel
import platform from "@rcompat/webview/linux-x64"; // Linux x64
import platform from "@rcompat/webview/windows-x64"; // Windows x64

Compiling to Executable

Bun

bun build app.ts worker.ts --compile --minify

Deno

deno compile --no-check --include worker.ts app.ts

Cross-Compilation

Generate platform-specific builds for distribution:

build.ts

import args from "@rcompat/args";
import FileRef from "@rcompat/fs/FileRef";

const p = "--platform=";
const platform =
  args.find(arg => arg.startsWith(p))?.slice(p.length) ?? "default";

await new FileRef(import.meta.dirname).join("worker.ts").write(`
  import platform from "@rcompat/webview/${platform}";
  import Webview from "@rcompat/webview";

  const webview = new Webview({ platform });
  webview.navigate("http://localhost:8181");
  webview.run();
`);

Build for Linux from macOS

# Bun
bun build.ts --platform=linux-x64
bun build app.ts worker.ts --compile --target=bun-linux-x64 --minify

# Deno
deno -A build.ts --platform=linux-x64
deno compile --no-check --include worker.ts --target=x86_64-unknown-linux-gnu app.ts

Examples

Desktop app with graceful shutdown

// app.ts
import serve from "@rcompat/http/serve";

const html = `
  <!DOCTYPE html>
  <html>
    <body>
      <h1>My Desktop App</h1>
      <button onclick="alert('Clicked!')">Click Me</button>
    </body>
  </html>
`;

const server = await serve(
  () => new Response(html, { headers: { "Content-Type": "text/html" } }),
  { port: 8181 }
);

// Bun
const worker = new Worker("worker.ts");

// Deno
const worker = new Worker(new URL("worker.ts", import.meta.url).href, {
    type: "module",
});

// graceful shutdown when webview closes
worker.addEventListener("message", (event) => {
  if (event.data === "destroyed") {
    server.stop();
  }
});

Static HTML app

import platform from "@rcompat/webview/default";
import Webview from "@rcompat/webview";

const webview = new Webview({ platform, debug: true });

webview.size = { width: 400, height: 300, hint: 3 }; // Fixed size

webview.html = `
  <!DOCTYPE html>
  <html>
    <head>
      <style>
        body {
          font-family: system-ui;
          display: flex;
          align-items: center;
          justify-content: center;
          height: 100vh;
          margin: 0;
          background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
          color: white;
        }
      </style>
    </head>
    <body>
      <h1>Hello, Desktop!</h1>
    </body>
  </html>
`;

webview.run();

Supported Platforms

Platform Architecture Export
macOS ARM64 darwin-arm64
macOS x64 darwin-x64
Linux x64 linux-x64
Windows x64 windows-x64

Cross-Runtime Compatibility

Runtime Supported
Bun ✓
Deno ✓
Node.js Planned

License

MIT

Contributing

See CONTRIBUTING.md in the repository root.