Orqestria Download
← Back to Tauri foundation team

Skill · Version 1.0.0

Verify packaged desktop apps

Checks the shipped executable's paths, native binaries and startup behavior beyond development-mode success.

desktop-packaging-verification

Team members using this skill

See how it helps

When is it useful?

Use when a desktop app works locally but fails after packaging.

What does it help you do?

  • Resolves application resources separately from writable user-data locations.
  • Checks executable sidecars, archive extraction and paths containing spaces or accents.
  • Launches an isolated profile and records actual tested platforms.

Try asking this

Test the packaged app from a non-ASCII path with a minimal GUI environment and verify clean process shutdown. Launch from a folder with spaces and Hungarian accents, create a file and quit. Resources must resolve correctly and owned child processes must terminate.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

Desktop Packaging & Verification

An application that runs in npm run dev frequently fails the moment it is packaged into a read-only .app bundle or Windows installer. Always design asset, binary, and database paths for the packaged layout and smoke-test the actual packaged binary.

Dev vs. Packaged Path Invariants

Never use process.cwd(), __dirname assumptions, or relative ./data writes for mutable files or external binaries:

Resource Type Dev Mode Packaged Mode (app.isPackaged / Tauri bundle) Mutability
Bundled UI Assets Local dev server (http://localhost:...) Inside app.asar or embedded Tauri asset protocol (tauri://localhost / https://tauri.localhost) Read-Only
Native Addons (.node), Sidecar Binaries, SQLite Migrations Repo workspace paths process.resourcesPath / app.asar.unpacked (Electron extraResources / asarUnpack) or Tauri BaseDirectory::Resource Read-Only (Never write here!)
User Database (sqlite), Config, State Scoped dev profile dir (~/.app-dev) app.getPath('userData') / Tauri app.path().app_data_dir() Read/Write (Persists across app updates)
Ephemeral Scratch & Socket Files OS temp dir app.getPath('temp') Read/Write (Cleared on reboot)
Application & Subprocess Logs Console + dev log dir app.getPath('logs') (~/Library/Logs/<App> on macOS, %USERPROFILE%\AppData\Roaming\<App>\logs on Windows) Read/Write (Rotated)

Native Addons, Sidecars & Archive Unpacking

  1. OS Kernel Execution Constraint:
    • Operating system APIs (execve, CreateProcess, dlopen, LoadLibrary) cannot execute binaries or load native .node / .dll / .dylib libraries directly from inside a virtual app.asar archive.
    • Configure asarUnpack: ["**/*.node", "**/bin/**"] or extraResources in electron-builder / Electron Forge (or bundle.externalBin / bundle.resources in tauri.conf.json), and resolve paths dynamically using a helper that switches on app.isPackaged.
  2. Test Paths with Spaces and Non-ASCII Characters:
    • Packaged apps live in /Applications/My App.app/Contents/Resources/... or C:\Users\Gábor Laczkovszki\AppData\Local\Programs\.... Quote or array-pass every path and test explicitly in a directory containing spaces and accented characters.

Packaged Build Smoke-Test Protocol

Never mark a desktop packaging task complete based only on tsc or cross-compilation exit code 0:

  1. Build the unpacked directory target (electron-builder --dir / tauri build --debug --no-bundle or full installer) for the host OS/architecture.
  2. Launch the packaged executable with a clean test --user-data-dir (and minimal Finder-like PATH).
  3. Verify that the window renders without CSP/asset errors, the local server/database initializes in userData, external CLI detection works, and quitting the app terminates all child processes cleanly with exit code 0.
  4. State explicitly which platforms/architectures were verified on a real OS and which were only build-checked.

Included files 1

  • SKILL.md