Use when you need to build, automate, or document desktop-style browser windows and browser automation flows with Bun's `Bun.WebView` API. Reach for this skill when creating a new `Bun.WebView`, configuring constructor parameters, calling instance methods, using page state properties, or wiring CDP and event-based integrations.
Installation
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Use when you need to build, automate, or document desktop-style browser windows and browser automation flows with Bun's `Bun.WebView` API. Reach for this skill when creating a new `Bun.WebView`, configuring constructor parameters, calling instance methods, using page state properties, or wiring CDP and event-based integrations.
metadata
{"mintlify-proj":"bun","version":"1.0"}
Bun WebView Skill
When to Use This Skill
Use this skill when you are:
Creating a desktop window or browser automation target with Bun's Bun.WebView API
Loading HTML, navigating to URLs, or evaluating JavaScript in a page
Documenting or implementing Bun.WebView constructor options
Looking up instance methods such as navigate(), evaluate(), screenshot(), click(), type(), press(), scroll(), resize(), goBack(), goForward(), reload(), or cdp()
Using page state properties like view.url, view.title, and view.loading
Handling EventTarget events, especially Chrome backend CDP events dispatched as MessageEvent
Configuring backend selection, console capture, and persistent profiles
Product Summary
Bun.WebView is available starting in Bun v1.3.12.
Bun's Bun.WebView API provides a native webview/browser automation surface you can create directly from Bun. It supports multiple backends, including WebKit and Chrome, and is intended for lightweight desktop apps, internal tools, testing flows, and browser-driven automation without a full Electron-style stack.
At a high level, you:
Create a new Bun.WebView instance
Pass constructor options to configure the backend, initial page, logging, and persistence
Use instance methods to navigate, evaluate code, click, type, scroll, resize, capture screenshots, or send raw CDP commands
Read page state from properties like view.url, view.title, and view.loading
Listen for events because Bun.WebView extends EventTarget
One browser subprocess is shared per Bun process. Additional new Bun.WebView() calls open tabs in the same instance.
Select the backend or provide a custom Chrome executable and arguments
url
string
Initial URL to load
headless
boolean
Defaults to true; only true is implemented
console
typeof console or (type, ...args) => void
Capture page logs
dataStore
"ephemeral" | { directory: string }
Persist browser profile data across runs (default "ephemeral")
Parameter guidance
Use backend: "webkit" for the WebKit backend
Use backend: "chrome" for the built-in Chrome backend
Use backend: { type: "chrome", path, argv } when you need a specific Chrome/Chromium binary or launch flags
Prefer url for most real usage
Use console: globalThis.console to forward page logs directly to Bun's console
Use console: (type, ...args) => { ... } when you need custom console handling
Use dataStore when you need cookies, sessions, or persistent browser state across runs
3. Instance methods
After creating a Bun.WebView, you control it through instance methods. Most of the high-level automation methods work across both backends, while cdp() is Chrome-only.
Navigation and evaluation
navigate(url) — navigate to a URL
evaluate(expr) — evaluate a JavaScript expression in the page; wrap statement sequences in an IIFE
goBack() — navigate backward in history
goForward() — navigate forward in history
reload() — reload the current page
Screenshots and automation
screenshot({ format, quality, encoding }) — capture a PNG, JPEG, or WebP screenshot
click(x, y) — click at viewport coordinates
click(selector) — click an element matched by a CSS selector
type(text) — type text into the focused element
press(key, options?) — press a key with optional options
scroll(dx, dy) — scroll by delta
scrollTo(selector) — scroll to an element matched by a selector
Viewport and protocol control
resize(width, height) — resize the viewport
cdp(method, params?) — send a raw Chrome DevTools Protocol call
close() — destroy the page; rejects pending promises; idempotent
Page state properties
view.url — current page URL
view.title — current page title
view.loading — whether the page is currently loading
view.onNavigated — fires after each successful navigation, before navigate() resolves
view.onNavigationFailed — fires after each failed navigation, before navigate() rejects
Pick "webkit" or "chrome" based on your needs, or provide a custom Chrome executable object.
4. Add automation steps
Use navigate(), evaluate(), click(), type(), press(), scroll(), and resize().
5. Add persistence and logging
Configure dataStore and console if needed.
6. Add advanced Chrome integration
Use cdp() and event listeners only when higher-level methods are not enough.
Best Practices
Start with a minimal constructor and add options incrementally
Use Bun v1.3.12 or newer
Prefer url plus automation methods for most workflows
Choose the backend explicitly when behavior matters
Use console during development to capture page logs
Use console: globalThis.console or a callback, not true
Use dataStore when you need persistent browser state
Prefer high-level methods like click(), type(), and scrollTo() before dropping to cdp()
Treat evaluate() as a sharp tool; keep expressions focused and deterministic
Remember that evaluate() accepts expressions, so wrap statement blocks in an IIFE when needed
Remember that one browser subprocess is shared per Bun process, and additional views open tabs in the same instance
Common Gotchas
Version requirement: Bun.WebView starts in v1.3.12
Backend differences: Chrome-specific protocol behavior is available through cdp() and event dispatch, even though the documented high-level methods work across both backends
Shared browser process: additional new Bun.WebView() calls open tabs in the same browser instance for the current Bun process
Custom Chrome launch config: if you use backend: { type: "chrome", path, argv }, make sure the executable path and arguments are valid on the target machine
Overusing evaluate(): use it for focused DOM or JS tasks, not as your entire automation architecture
Expression-only evaluation: evaluate() wraps your code as await (${script}), so statement blocks must be wrapped in an IIFE
Selector fragility: click(selector) and scrollTo(selector) depend on stable DOM structure
CDP event handling: on Chrome, protocol events arrive as MessageEvent with payload in event.data
Verification Checklist
Before you ship or hand off WebView work:
Confirm Bun is v1.3.12 or newer
Verify the app can create a new Bun.WebView instance
Confirm constructor parameters like backend, console, and dataStore are documented and used intentionally
Test key instance methods like navigate(), evaluate(), screenshot(), click(), type(), press(), scroll(), resize(), goBack(), goForward(), and reload()
Verify page state properties like view.url, view.title, and view.loading
Test Chrome backend cdp() calls if you rely on them
Test event handling if you consume Chrome CDP events
Confirm shared-process/tab behavior is acceptable for your app design
Test on the actual target OS and backend combination
Reference Template for Agent Work
When documenting or implementing Bun WebView, structure your output around:
Note: Bun.WebView starts in Bun v1.3.12. The documented high-level methods listed in this skill work across both WebKit and Chrome backends, while Chrome also exposes raw CDP access and dispatches protocol events through EventTarget as MessageEvent objects with payload in event.data.
