DEV Community

Leo Zhang
Leo Zhang

Posted on

Fixing the Tauri v2 white screen in production (and the 6 release bugs right behind it)

#tauri #rust #webdev #devops

Your Tauri app runs perfectly with tauri dev. You build it, double-click the bundle, and... a blank white window. Welcome to the part of shipping a desktop app nobody warns you about: the release.

Below are the release issues that eat the most time, with fixes you can paste in. The white screen goes first, because everyone hits it.

TL;DR

  • White screen in prod -> your assets load from the wrong place. Set Vite base: './', fix frontendDist, switch the router to hash history.
  • macOS "app is damaged" -> it isn't; it's unsigned and quarantined. xattr -cr unblocks testers; sign + notarize for the real fix.
  • Windows SmartScreen -> unsigned binaries have no reputation. Sign with a cert (an EV cert clears the warning instantly).

1. The white screen

The bundled webview doesn't load assets from a web-server root - it serves them over a custom protocol. Front-end builds that emit absolute paths (/assets/index.js) resolve to the wrong place, and SPA routers in history mode hit the same wall.

Fix it in three moves:

// vite.config.ts
export default defineConfig({
  base: './',          // emit ./assets/... instead of /assets/...
  build: { outDir: 'dist' },
});
Enter fullscreen mode Exit fullscreen mode 
// src-tauri/tauri.conf.json
"build": {
  "frontendDist": "../dist",
  "beforeBuildCommand": "npm run build"
}
Enter fullscreen mode Exit fullscreen mode

And if you use a router, switch it to hash history so deep links resolve inside the webview.

2. macOS says your app is "damaged"

It isn't. An unsigned/un-notarized app gets quarantined by Gatekeeper, and the error message is misleading. For a tester right now:

xattr -cr "/Applications/YourApp.app"
Enter fullscreen mode Exit fullscreen mode

The real fix is a Developer ID Application certificate ($99/yr Apple Developer account) plus notarization. With the Apple env vars present (APPLE_CERTIFICATE, APPLE_SIGNING_IDENTITY, APPLE_ID, APPLE_PASSWORD, APPLE_TEAM_ID), tauri build signs and notarizes for you.

3. Windows SmartScreen blocks the installer

Unsigned binaries have no reputation, so SmartScreen warns until enough people install - or until you sign with a recognized cert. An OV cert earns trust slowly; an EV cert clears the warning immediately. Configure it in the bundle:

"bundle": { "windows": {
  "certificateThumbprint": "<THUMBPRINT>",
  "digestAlgorithm": "sha256",
  "timestampUrl": "http://timestamp.digicert.com"
}}
Enter fullscreen mode Exit fullscreen mode

The other four

These three are just the start. The ones that bite next:

  1. Two windows / single-instance race - register tauri-plugin-single-instance first, before any other plugin.
  2. An updater that silently never fires - the keypair, the public key in config, and latest.json's signatures must all come from the same key.
  3. DMG builds hanging in CI - the pretty DMG drives Finder via AppleScript; headless runners have no Finder session.
  4. Wrong identifier / missing resources - never ship com.tauri.dev; declare every resource/externalBin.

I wrote all seven up with paste-in fixes, a signed cross-platform GitHub Actions release.yml, a secrets table, and a pre-flight checklist in a small kit: Tauri v2 Ship-It Kit - launch price $12 for the first 50 -> https://zhlwave4.gumroad.com/l/iazysv/SHIPIT

Either way, save yourself the 2am debugging.

Built for Tauri v2. Confirm Apple/Microsoft signing specifics against the official docs before a public launch.

Top comments (0)