From dc2aad14b556f7136996e76ace9b9a8c5df6ae43 Mon Sep 17 00:00:00 2001 From: Luna <279187109+lunadogbot@users.noreply.github.com> Date: Wed, 29 Apr 2026 11:48:48 +0000 Subject: [PATCH] docs: add `deno desktop` reference page (2.8) Adds a CLI reference page for the new (experimental) deno desktop subcommand which builds self-contained desktop apps from a Deno project. Documents the three rendering backends (cef / webview / raw), framework auto-detection, HMR, the Deno.BrowserWindow / Deno.Tray / Deno.dock APIs, the unified DevTools session, the auto-updater, the cross-compile output formats, and the new \`desktop\` block in deno.json. Marks the surface as still evolving. Adds entries to the CLI index and sidebar. Refs denoland/deno#33441 --- runtime/_data.ts | 4 + runtime/reference/cli/desktop.md | 162 +++++++++++++++++++++++++++++++ runtime/reference/cli/index.md | 2 + 3 files changed, 168 insertions(+) create mode 100644 runtime/reference/cli/desktop.md diff --git a/runtime/_data.ts b/runtime/_data.ts index 54632587b..a80f1c517 100644 --- a/runtime/_data.ts +++ b/runtime/_data.ts @@ -144,6 +144,10 @@ export const sidebar = [ title: "deno deploy", href: "/runtime/reference/cli/deploy/", }, + { + title: "deno desktop", + href: "/runtime/reference/cli/desktop/", + }, { title: "deno doc", href: "/runtime/reference/cli/doc/", diff --git a/runtime/reference/cli/desktop.md b/runtime/reference/cli/desktop.md new file mode 100644 index 000000000..6759e9343 --- /dev/null +++ b/runtime/reference/cli/desktop.md @@ -0,0 +1,162 @@ +--- +last_modified: 2026-04-29 +title: "deno desktop" +command: desktop +openGraphLayout: "/open_graph/cli-commands.jsx" +openGraphTitle: "deno desktop" +description: "Build self-contained desktop applications from a Deno project" +--- + +The `deno desktop` subcommand builds a self-contained desktop application from +a Deno project. The compiled binary bundles the Deno runtime, your code, and a +rendering backend (Chromium, the OS webview, or a raw windowing system) into +one redistributable executable. + +:::info Experimental + +`deno desktop` is new in Deno 2.8 and the API surface is still evolving. The +exact flag names, configuration keys, and TypeScript types described here may +change before the feature is considered stable. + +::: + +## Quick start + +```sh +# Compile the current project into a desktop app +deno desktop main.ts + +# Or detect a framework and compile from a directory +deno desktop . +``` + +The output is a redistributable bundle for the host OS — `.app` on macOS, +`.exe` (with a sibling DLL directory) on Windows, an app directory or +`AppImage` on Linux. + +## Backends + +`deno desktop` ships three rendering backends. Pick one in `deno.json` under +`desktop.backend`: + +| Backend | Engine | When to use it | +| --------- | ---------------------------- | --------------------------------------------------------- | +| `cef` | Bundled Chromium (default) | Predictable rendering across platforms | +| `webview` | Operating-system webview | Smaller binaries; uses the OS-provided web engine | +| `raw` | `winit`, no web engine | Custom windowing only — your app draws everything itself | + +Backend binaries are downloaded once from +[`github.com/denoland/wef/releases`](https://github.com/denoland/wef), pinned +via `Cargo.lock`, SHA-256 verified, and cached under `/wef//`. +For local development against a wef checkout, set `WEF_DEV_DIR`. + +## Framework auto-detection + +Pointing `deno desktop` at a directory triggers the same framework detection +used by [`deno compile`](/runtime/reference/cli/compile/). Supported +frameworks: Next.js, Astro, Fresh, Remix, Nuxt, SvelteKit, SolidStart, +TanStack Start, and Vite (SSR mode). Production builds run by default; dev +builds run under `--hmr`. `Deno.serve()` in your entry point auto-binds to the +port the webview navigates to via the `DENO_SERVE_ADDRESS` env var. + +## HMR + +```sh +deno desktop --hmr . +``` + +For framework projects, `--hmr` runs the framework's own dev server. For +non-framework apps, Deno watches the file tree and uses +`Debugger.setScriptSource` to hot-swap modules — keeping the runtime and the +rendering backend alive across reloads. + +## `Deno.BrowserWindow` API + +A new `Deno.BrowserWindow` API exposes window lifecycle and webview +integration. Highlights: + +- Show / hide / focus / close / reload, size and position, always-on-top. +- Navigation control. +- `bind(name, handler)` / `unbind(name)` to expose RPC functions to the webview + JavaScript at `bindings.()`. +- `executeJs(code)` to run code in the webview context. +- App and context menus, keyboard / mouse / wheel / resize / focus events. +- Native window handle for platform-specific integration. + +Built-in browser dialogs are wired up too: `prompt()`, `alert()`, and +`confirm()` show native popups, and uncaught errors surface as native alerts — +optionally `POST`ing to the URL configured at `desktop.errorReporting.url`. + +`Deno.dock` (macOS) and `Deno.Tray` (cross-platform) provide system-tray / +status-area icons with tooltips, dark-mode variants, and context menus. + +## DevTools + +Pass `--inspect`, `--inspect-brk`, or `--inspect-wait` to attach DevTools. +Unlike standard `deno run`, `deno desktop` exposes a single DevTools session +with **both** isolates as targets — the Deno runtime V8 and the renderer V8 — +so you get one Console dropdown (Renderer / Deno) and one Sources panel. +`--inspect-brk` pauses both isolates before navigation. + +## Auto-update + +Apps built with `deno desktop` can update themselves in the background: + +```ts +console.log(Deno.desktopVersion); + +await Deno.autoUpdate({ + url: "https://updates.example.com", + interval: "1h", + onUpdateReady() {/* show user a "restart" prompt */}, + onRollback() {/* the previous launch failed; we rolled back */}, +}); +``` + +The runtime polls `/latest.json`, applies bsdiff patches to the runtime +dylib, stages the update for the next launch, and rolls back automatically if +the new version fails to start. + +## Cross-compile and distribution + +Pass `--target ` (or `--all-targets`) to build for another platform. +The command downloads the matching prebuilt `denort` and WEF backends. + +| Platform | Outputs | +| -------- | ---------------------------------------------------------- | +| macOS | `.app` bundle (framework under `Contents/Frameworks/`), `.dmg` via `hdiutil` | +| Windows | `.exe` plus a sibling DLL directory | +| Linux | App directory, `.AppImage` via `appimagetool` | + +Code-signing / notarization (`--sign`), Windows MSI, Linux `.deb` / `.rpm`, +and a few other niceties (`Deno.notifications`, `Deno.clipboard`, +`Deno.secureStorage`) are not yet implemented at the time of this writing. + +## Configuration in `deno.json` + +```jsonc +{ + "desktop": { + "app": { + "name": "MyApp", + "icons": { + "macos": "./icons/icon.icns", + "windows": "./icons/icon.ico", + "linux": "./icons/icon.png" + } + }, + "backend": "cef", + "output": { + "macos": "./dist/macos", + "windows": "./dist/windows", + "linux": "./dist/linux" + }, + "release": { + "baseUrl": "https://updates.example.com" + }, + "errorReporting": { + "url": "https://errors.example.com/report" + } + } +} +``` diff --git a/runtime/reference/cli/index.md b/runtime/reference/cli/index.md index e910755dc..67faf73ac 100644 --- a/runtime/reference/cli/index.md +++ b/runtime/reference/cli/index.md @@ -51,6 +51,8 @@ below for more information on each subcommand. - [deno doc](/runtime/reference/cli/doc/) - generate documentation for a module - [deno deploy](/runtime/reference/cli/deploy) - Manage and publish your projects on the web +- [deno desktop](/runtime/reference/cli/desktop/) - build a desktop app from + the current Deno project - [deno fmt](/runtime/reference/cli/fmt/) - format your code - [deno info](/runtime/reference/cli/info/) - inspect an ES module and all of its dependencies