Skip to main content

Ship a desktop app

Ship the shell as a native desktop app. The CLI uses Tauri 2 and writes the wrapper into dist/app/ so you do not commit native project files.

Browser PWA vs native (iOS)​

The same React / Vite shell runs in both hosts. Status-bar behavior does not:

HostHow it runsTop chrome
Safari / Home Screen PWAStandalone web appiOS 26/27 Liquid Glass — system status sampling / gradient. Shellui skips stacking its own status scrims and does not set theme-color.
Tauri iOS (App Store)Native WKWebViewNo Home Screen PWA system gradient. You control insets with viewport-fit=cover + env(safe-area-inset-*) (already in the shell).
Tauri desktopNative webviewOverlay titlebar / traffic lights (macOS).

Detect the live native shell in app code with window.__TAURI__ (or Shellui’s isTauriRuntime()). Prefer that over the CLI --target tauri build flag when deciding UI — a browser tab of a tauri-targeted build must not get native chrome.

import { isTauriRuntime, isHomeScreenPwa } from '@shellui/core';

if (isTauriRuntime()) {
// App Store / desktop WKWebView — native-controlled chrome
}

if (isHomeScreenPwa()) {
// Safari "Add to Home Screen" only
}

html[data-shellui-host] is set to browser | pwa | tauri for CSS.

App Store recommendation: distribute the iOS build via Tauri so you avoid the iOS Home Screen PWA status gradient. Keep the web PWA for install-from-Safari users who accept platform chrome. Always verify on a real iPhone/iPad — Tauri mobile has had its own inset quirks.

The shell document already ships:

<meta
name="viewport"
content="width=device-width, initial-scale=1.0, viewport-fit=cover"
/>

Layouts pad with --shellui-safe-area-* (env(safe-area-inset-*)). On iOS WKWebView, if UIKit still shrinks the scroll view, set contentInsetAdjustmentBehavior = .never on the webview (e.g. via a Tauri iOS insets plugin) so edge-to-edge paint matches CSS safe-area.

Prerequisites​

  1. Rust via rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Confirm with cargo --version and rustc --version. If those fail, restart the terminal or run source ~/.cargo/env. failed to run 'cargo metadata' means Cargo is missing or off PATH.

  1. Node.js 18+ and a package manager.

Platform extras - see Tauri prerequisites:

  • macOS: Xcode Command Line Tools (xcode-select --install)
  • Windows: Visual Studio C++ Build Tools, WebView2
  • Linux: webkit2gtk and related packages listed in Tauri docs

Commands​

shellui dev --app
shellui build --app
npx shellui build --app --bundles app,dmg

shellui start --app is the same as dev --app. On first run the CLI generates dist/app/, installs desktop build tools if needed (for example @tauri-apps/cli), and syncs root tauri.conf.json plus shellui.config.json port into the wrapper.

CommandOutput
shellui builddist/web/ static site
shellui build --appdist/web/ plus .app on macOS under dist/app/
shellui build --app --bundles app,dmgAbove plus a .dmg

Everything under dist/ is generated and gitignored.

Configuration​

Optional tauri.conf.json next to shellui.config.json:

{
"$schema": "https://schema.tauri.app/config/2",
"productName": "Shellui",
"identifier": "com.shellui.app",
"bundle": {
"icon": ["static/icon.png"]
}
}
FieldUse
productNameDock / installer / window name for bundled apps. Defaults to package.json name with the first letter capitalized. During tauri dev, macOS uses the Cargo package name (kept in sync from productName)
identifierBundle id. Defaults from the product name
bundle.iconSource icon(s) relative to the project root (prefer an opaque static/icon.png). The CLI runs tauri icon
app.windows[0]Optional window overrides. Overlay titlebar defaults stay unless you override them

From shellui.config.json: port is the dev URL (http://localhost:<port>); title is a fallback product name; favicon / appIcon are icon fallbacks when bundle.icon / static/icon.png are absent (appIcon is last and is a transparent chrome glyph). Prefer root tauri.conf.json for dock name and icon; keep title / appIcon for in-app chrome.

On macOS, the window uses an overlay titlebar with the title hidden. Close / minimize / zoom are the system traffic lights at the AppKit default position (Shellui does not move them, so the same build works on every macOS version). Every layout draws a 32px top strip centered on the lights line (y 16); controls in it are 24px with 16px icons. The left 80px of the strip is a drag-only safe area with nothing clickable in it; in native fullscreen the lights hide and the safe area shrinks to 12px. Strip backgrounds and spacers carry data-tauri-drag-region (needs core:window:allow-start-dragging), so dragging moves the window and a double click zooms it; every control carries data-shellui-no-drag. Opening the same --target tauri URL in a browser drops the strip. Back / Forward stay in Tauri chrome (including native fullscreen). A full-width invisible 32px drag strip is mounted at the app root. Sidebar Back walks iframe history, including out of a login page.

Bundle targets​

shellui build --app passes --bundles to Tauri. Default is app only (on macOS, .app under dist/app/src-tauri/target/release/bundle/macos/). That skips flaky DMG packaging during local builds.

npx shellui build --app --bundles app,dmg

DMG lands under dist/app/src-tauri/target/release/bundle/dmg/. Other Tauri bundle targets (deb, rpm, appimage, msi, nsis) work the same way on Linux or Windows.

{
"scripts": {
"build:app": "shellui build --app",
"build:app:dmg": "shellui build --app --bundles app,dmg"
}
}

Icons​

Sync prefers tauri.conf.json → bundle.icon, then static/icon.png, then favicon / static/favicon.svg (not the transparent appIcon chrome glyph). The CLI generates PNG / ICNS / ICO via tauri icon, then falls back to bundled defaults. Use a solid-background square for the dock, padded to Apple's ~824/1024 grid on macOS. Keep appIcon as the mono mark for sidebar / app-bar chrome.

Sign in on the desktop​

A Tauri shell signs in through the system browser and returns on a custom-scheme deep link. This runs when backend.type is shellui inside a live Tauri webview. A browser tab ignores auth.desktopScheme. An unset scheme keeps the browser flow.

Set the scheme in shellui.config.json. Use the same lowercase value as desktop_redirect_scheme on the OAuth application. http, https, and other browser schemes are refused.

{
"auth": {
"desktopScheme": "shellui-playground"
}
}

Register that scheme in the project tauri.conf.json. The CLI copies plugins into dist/app/src-tauri/tauri.conf.json on shellui dev --app:

{
"plugins": {
"deep-link": {
"desktop": {
"schemes": ["shellui-playground"]
}
}
}
}

The generated app under dist/app/src-tauri also needs the opener and deep-link plugins. The first shellui dev --app copies the CLI template. Add the crates, register them, and allow them:

tauri-plugin-opener = "2"
tauri-plugin-deep-link = "2"
tauri::Builder::default()
.plugin(tauri_plugin_opener::init())
.plugin(tauri_plugin_deep_link::init())

In capabilities/default.json, add opener:default and deep-link:default next to the existing permissions.

When the sign-in link arrives, the shell brings its window to the front, so the user leaves the browser for the signed-in app. A repeated Return to app click does the same. This needs core:window:allow-unminimize, core:window:allow-show, and core:window:allow-set-focus. shellui start --app and shellui build --app add any that are missing to dist/app/src-tauri/capabilities/default.json, so an app created earlier gets them too.

Shellui calls plugin:opener|open_url and listens for deep-link://new-url over Tauri IPC. A web build leaves the plugin packages out. To use your own opener, call configureDesktopAuth before sign-in:

import { configureDesktopAuth } from '@shellui/core';
import { onOpenUrl } from '@tauri-apps/plugin-deep-link';
import { openUrl } from '@tauri-apps/plugin-opener';

configureDesktopAuth({ openUrl, onOpenUrl });

Sign-in opens GET /api/v1/authorize with redirect_to set to shellui-playground://callback, plus code_challenge and code_challenge_method=S256. Shellui stores the verifier in memory and in sessionStorage for that attempt.

The browser returns to shellui-playground://callback?shellui_auth_code=…. The shell posts auth_code, the same redirect_to, and code_verifier to POST /api/v1/oauth/session. The code lasts 120s.

A failed sign-in uses the same link with ?error= (for example pkce_required) or shellui_oauth_error. The shell shows a message. Logs omit the code, the verifier, and tokens.

Magic link sends the same redirect and challenge on POST /api/v1/magic-link/request. On Windows and Linux, add Tauri's single-instance plugin so the deep link reaches the running app.

Sign in during shellui start --app​

When auth.desktopScheme is set, the dev shell signs in with <scheme>-dev, for example shellui-playground-dev. Installed builds keep shellui-playground, so a dev session never takes links meant for an installed app. tauri dev gets the -dev scheme as its only deep-link scheme.

A local identity-service with DEBUG=true accepts the -dev variant of every scheme the company registers, so the admin list only needs shellui-playground. Production (DEBUG=false) accepts shellui-playground-dev only when that scheme is listed. An older identity-service refuses the redirect as an unregistered scheme. There, add the -dev scheme in Shellui admin as well.

macOS. macOS learns a URL scheme only from an installed .app, and tauri dev runs a bare binary. The CLI fills that gap with no app changes:

  • It builds a small background applet, dist/app/dev-link/<productName> Dev Link.app, and registers it for the -dev scheme.
  • The applet posts each link to the shell dev server on config.port, with a token that is new for every run.
  • The dev server passes the link to the dev window, which receives it as a normal deep-link://new-url event.

The CLI unregisters and deletes the applet when the dev session ends. If you see "Could not reach the dev server", the dev session has stopped.

Windows and Linux. The app registers the scheme itself at runtime, and the single-instance plugin hands the link from the second process to the running app. Add the crate for those targets:

[target.'cfg(any(windows, target_os = "linux"))'.dependencies]
tauri-plugin-single-instance = { version = "2", features = ["deep-link"] }

Register single-instance first, and register the schemes at runtime in debug builds:

let builder = tauri::Builder::default();
#[cfg(any(windows, target_os = "linux"))]
let builder = builder.plugin(tauri_plugin_single_instance::init(|app, _argv, _cwd| {
use tauri::Manager;
if let Some(window) = app.get_webview_window("main") {
let _ = window.set_focus();
}
}));
builder
.plugin(tauri_plugin_opener::init())
.plugin(tauri_plugin_deep_link::init())
.setup(|app| {
#[cfg(all(debug_assertions, any(windows, target_os = "linux")))]
{
use tauri_plugin_deep_link::DeepLinkExt;
app.deep_link().register_all()?;
}
Ok(())
})

Runtime registration writes a user-level association (registry on Windows, a .desktop file on Linux) for the -dev scheme only. It stays after the session, and the next dev run overwrites it.

Layout​

my-project/
├── shellui.config.json
├── static/
└── dist/
├── web/
└── app/

When developing Shellui itself, the monorepo exposes pnpm tauri:dev and pnpm tauri:build via tools/tauri/. Published-CLI apps use shellui dev --app and shellui build --app.

Troubleshooting​

failed to open icon .../icon.png. Remove dist/app and run shellui dev --app again.

bundle_dmg.sh failed (macOS). Look for .app under dist/app/src-tauri/target/release/bundle/macos/ - the app bundle can succeed when DMG packaging fails. Default --app skips DMG. If you requested app,dmg and it failed, unmount stale volumes (hdiutil info, then hdiutil detach /dev/diskX). This is a known flaky Tauri step.