Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/webviewjs/webview/llms.txt

Use this file to discover all available pages before exploring further.

The webview CLI tool packages your application into a single self-contained executable. Once built, the binary requires no Node.js, Deno, or Bun installation on the target machine — the runtime is bundled inside. The CLI auto-detects which runtime is currently executing it and uses that as the default, so running webview --build from inside a Bun project will use Bun’s compiler without any extra flags.
The CLI build feature is experimental. APIs and output formats may change between releases. Test your builds thoroughly on each target platform before distributing.

​
Quick Start

1

Install the CLI

The webview binary is included in the @webviewjs/webview package. Install it globally or use npx.
npm install -g @webviewjs/webview
# or use without installing:
npx @webviewjs/webview --build ...
2

Build your application

Point --input at your entry file and give the output binary a --name. The CLI writes to dist/ by default.
webview --build --input src/index.js --name myapp
3

Run the executable

# macOS / Linux
./dist/myapp

# Windows
dist\myapp.exe

​
Choosing a Runtime

The CLI supports three runtimes selected with --runtime (-R). If you omit the flag, the CLI detects the runtime it is currently running under: Bun → bun, Deno → deno, otherwise node.
RuntimeFlagCompiler used
Node.js (default)--runtime nodeNode.js Single Executable Application (SEA)
Deno--runtime denodeno compile
Bun--runtime bunbun build --compile
# Uses the Node.js Single Executable Application (SEA) workflow.
# Requires only node and npx on the build machine.
webview --build \
  --runtime node \
  --input src/index.js \
  --name myapp \
  --output dist

​
CLI Flags Reference

  -b, --build        Build the project into a standalone executable
  -R, --runtime      Runtime: node (default), deno, or bun
  -n, --name         Executable name (default: webviewjs)
  -i, --input        Entry file (default: index.js in cwd)
  -o, --output       Output directory (default: dist/)
  -r, --resources    Resources mapping JSON file (node runtime only)
  -d, --dry-run      Print what would happen without executing anything
  -h, --help         Show help
  -v, --version      Show version

​
Node.js SEA: How It Works

The Node.js runtime does not have a single compile command. The CLI automates the multi-step Single Executable Application workflow:
1

Write sea-config.json

The CLI writes a sea-config.json into the output directory pointing at your entry file and listing any bundled asset blobs.
2

Generate the blob

Runs node --experimental-sea-config sea-config.json to produce sea-prep.blob.
3

Copy the Node binary

Copies the current node executable into the output directory under your chosen name.
4

Remove the existing signature

On macOS uses codesign --remove-signature; on Windows uses signtool remove. Required before injection.
5

Inject the blob

Uses postject (fetched automatically via npx --yes postject) to embed the blob into the binary.
6

Re-sign the binary

On macOS signs with codesign --sign -; on Windows signs with signtool sign /fd SHA256 if available.

​
Bundling Assets with —resources (Node.js only)

The --resources flag accepts a path to a JSON file that maps asset names to source file paths. These assets are embedded inside the SEA blob and readable at runtime via node:sea. assets.json 
{
  "icon.png":    "./assets/icon.png",
  "config.json": "./config/production.json",
  "theme.css":   "./src/theme.css"
}

webview --build \
  --runtime node \
  --input src/index.js \
  --name myapp \
  --resources assets.json
Inside your application, read the embedded assets using the node:sea API: 
import { getAsset } from 'node:sea';

// Returns a Buffer
const iconBuffer = getAsset('icon.png');

// Parse JSON inline
const config = JSON.parse(
  new TextDecoder().decode(getAsset('config.json'))
);
The --resources flag is only supported for the node runtime. Deno and Bun have their own asset-bundling mechanisms (Deno.readFile with a --include flag, or Bun’s built-in bundler).

​
Dry Run Mode

Pass --dry-run (-d) to preview what the CLI would do without actually running any commands or writing any files. Useful for verifying paths before a real build. 
webview --build \
  --runtime node \
  --input src/index.js \
  --name myapp \
  --dry-run

# Output:
# Dry run: building /project/src/index.js to /project/dist using node runtime

​
Output Directory Structure

After a successful build the dist/ directory contains: 
dist/
├── myapp           (or myapp.exe on Windows)
├── sea-config.json (intermediate — safe to delete)
└── sea-prep.blob   (intermediate — safe to delete)
The intermediate Node.js files (sea-config.json, sea-prep.blob) are left in place so you can inspect them or re-run individual SEA steps manually if needed. They are not required to run the final binary.

​
Platform Notes

PlatformNode SEADeno compileBun compile
Windows✅ .exe appended automatically✅ .exe appended automatically✅ .exe appended automatically
macOS✅ Ad-hoc signed with codesign -s -✅ Ad-hoc signed automatically✅ Sign manually after build
Linux✅ No signing needed✅✅

​
Code Signing for Distribution

The CLI signs the Node.js SEA binary with codesign --sign - (an ad-hoc identity). For App Store or notarized distribution you must re-sign with your Developer ID certificate after the build:
codesign --force --deep --sign "Developer ID Application: Your Name (TEAMID)" dist/myapp
codesign --verify dist/myapp
The CLI calls signtool sign /fd SHA256 <binary> if signtool is available on PATH. Failures are logged as warnings but do not abort the build. For distribution, sign with your code-signing certificate:
signtool sign /n "Your Company" /fd SHA256 /tr http://timestamp.digicert.com dist\myapp.exe
  • Node SEA does not support cross-compilation. Build on the target OS.
  • Deno: pass --target directly to deno compile. Use a custom build script rather than the webviewjs CLI when targeting a different OS.
  • Bun: pass --target to bun build. Same recommendation — use a custom script for cross-compile targets.

​
Additional Build Examples

# Custom output directory and binary name
webview --build --runtime bun \
  --input src/main.ts \
  --name "MyDesktopApp" \
  --output ./release

# Node.js SEA with embedded assets
webview --build --runtime node \
  --input src/main.js \
  --name myapp \
  --resources assets.json \
  --output ./dist

# Dry-run to verify paths before committing to a slow SEA build
webview --build --runtime node \
  --input src/main.js \
  --name myapp \
  --dry-run

# Deno — TypeScript entry point, output to a release folder
webview --build --runtime deno \
  --input src/main.ts \
  --name myapp \
  --output ./release

Build docs developers (and LLMs) love

Get started for freeTalk to us