Nextjs To Tauri

Next.js 16 → Tauri 2 Desktop App

Overview

Wrap a client-side Next.js 16 (App Router) app in a thin Tauri 2 native shell. The React code is untouched; Tauri serves the static export from its embedded asset server. Build in GitHub Actions so no local Rust is needed.

Core principle: Tauri loads the static export over its own asset protocol — which behaves differently from a real HTTP server. Most migration pain is path/routing resolution, not React.

When to use

• The app is (or can be) a static export (output: "export") — diffing/formatting/calculator/viewer tools, no SSR-at-runtime needed.
• You want a desktop/portable .exe, .dmg, .AppImage, optionally with auto-update.

Do NOT use when the app needs a live Node server at runtime (real API routes, SSR, server actions). Tauri can bundle a sidecar server, but that's a different, heavier playbook.

Procedure

Do these in order. Copy-paste templates live in the supporting files.

1. Verify latest versions first (they drift — never trust the numbers in templates):

   • npm: npm view @tauri-apps/cli version (+ plugin-opener, plugin-updater)
   • crates: curl -sA x https://crates.io/api/v1/crates/tauri | node -p "JSON.parse(require('fs').readFileSync(0)).crate.max_stable_version" (repeat for each tauri-plugin-*)
   • actions: gh api repos/actions/checkout/releases/latest --jq .tag_name (+ actions/setup-node, Swatinem/rust-cache, actions/upload-artifact; tauri-apps/tauri-action@v1 is the moving major tag — check its README, not the release list)

2. Gate static export on Tauri in next.config.*, driven by an EXPLICIT build flag rather than Tauri's auto-injected TAURI_ENV_PLATFORM (gotcha #1). Merge into your existing config, keeping the next-intl plugin wrapper:

   // The NextConfig annotation is load-bearing: spreading `{ output: "export" }` into an
   // un-annotated object literal widens output to `string`, and withNextIntl() then
   // rejects it — `yarn build:tauri` fails type-checking before it ever builds.
   import type { NextConfig } from "next";
   import createNextIntlPlugin from "next-intl/plugin";
   const withNextIntl = createNextIntlPlugin();
   
   const isDev = process.env.NODE_ENV === "development";
   const isTauri = process.env.TAURI_BUILD === "1"; // set by `yarn build:tauri`
   
   const nextConfig: NextConfig = {
     // ...your existing config...
     ...(isDev ? {} : { output: "export" }),       // export is build-only (gotcha #2)
     ...(isTauri ? { trailingSlash: true } : {}),   // Tauri-only (gotcha #1)
     images: { unoptimized: true },
   };
   
   export default withNextIntl(nextConfig);  // keep your existing wrapper(s)
   

   Add the flag-setting script (yarn add -D cross-env) — tauri.conf's beforeBuildCommand runs it, NOT plain yarn build:

   // package.json → "scripts"
   "build:tauri": "cross-env TAURI_BUILD=1 next build"
   

3. Scaffold (CLI steps are JS — no Rust needed):

   yarn add -D @tauri-apps/cli@latest
   yarn tauri init --ci --app-name "<app>" --window-title "<Title>" \
     --frontend-dist "../out" --dev-url "http://localhost:3000" \
     --before-dev-command "yarn dev" --before-build-command "yarn build:tauri"
   # The source must be SQUARE (the CLI says "squared PNG or SVG") and 1024x1024 — the
   # generated .icns carries a 1024 layer, so a 512 source is upscaled 2x for macOS.
   yarn tauri icon public/logo.png
   rm -r src-tauri/icons/{android,ios}   # desktop-only; they are directories, hence -r
   

   Then fix .gitignore — see gotcha #3.

4. Edit src-tauri/ config & Rust. Copy from tauri-files.md: tauri.conf.json (window url, updater, webviewInstallMode, portable mainBinaryName), Cargo.toml (plugin deps + release profile), src/lib.rs (plugin registration + tray + single-instance), capabilities/default.json (permissions).

5. Frontend integration (only the features you need). Copy from frontend-integration.md into one src/app/desktop/ folder — desktop-only files scattered through utils//hooks/ get lost (see that file's opening note): external-links util (opener-based), auto-update hook, and — for next-intl apps — the remember-language hook. Mount them in one "use client" component rendered inside your providers (e.g. antd <App>, inside NextIntlClientProvider). That component also installs the global external-link interceptor (gotcha #10). Switch locales with plain router.push (soft nav works in Tauri — never hard-nav a switch); if you remember the language, guard the launch redirect with a module-level flag (gotcha #11).

6. Version single-source + CI. Add src-tauri/update-version.js and an update-version script (copies package.json version into tauri.conf.json). Copy desktop-build.yml for cross-platform builds, signing, draft release with latest.json, and the portable-exe steps.

   • Make the git tag the single source of truth (the template does this): on tag push, npm pkg set version="${GITHUB_REF_NAME#v}" (guarded if: github.event_name == 'push') runs before update-version, so installer filenames, the embedded app version and tagName: v__VERSION__ all equal the tag — you set the version by tagging, never by bumping branches. Do NOT point tagName at github.ref_name (gotcha #13).
   • If you skip injection, the pushed git tag MUST equal package.json version (v3.0.0 ↔ "version": "3.0.0"). tauri-action expands __VERSION__ from the app version, and the portable-exe step uploads to v${APP_VERSION} — a mismatch silently breaks the portable upload.
   • Windows is fully covered; macOS/Linux are not signed. Unsigned .dmg/.app is blocked by macOS Gatekeeper, and unsigned .AppImage triggers warnings. If you ship beyond Windows, add Apple notarization / codesigning secrets — out of scope here.

7. Auto-update signing keys (only if shipping updates):

   yarn tauri signer generate --ci -p "" -w src-tauri/app.key -f   # private key — gitignore it, NEVER commit (gotcha #7)
   cat src-tauri/app.key.pub   # paste this base64 into tauri.conf.json plugins.updater.pubkey
   

   The CI signing step needs the private key as a repo secret — without it every signed build fails. The agent doing the migration usually can't set repo secrets, so it MUST remind the user to run this (or set it in the GitHub UI):

   gh secret set TAURI_SIGNING_PRIVATE_KEY < src-tauri/app.key   # bash / Git Bash
   # only if you generated the key WITH a password (not `-p ""`):
   gh secret set TAURI_SIGNING_PRIVATE_KEY_PASSWORD
   

   PowerShell has no < redirection — pipe instead:

   Get-Content src-tauri/app.key -Raw | gh secret set TAURI_SIGNING_PRIVATE_KEY
   

   Manual path: repo → Settings → Secrets and variables → Actions → New repository secret.

8. Verify (without Rust): yarn build:tauri, then confirm the export shape:

   ls out/en/index.html   # MUST exist (not out/en.html) — proves trailingSlash worked
   

   The Rust shell (tray/single-instance API) only compiles in CI — flag that you can't compile it locally and let the first Actions run validate it.

Handoff — remind the user (manual, easy to forget, fail silently)

The code migration is done by the agent; these steps need the human and break things quietly if skipped. After migrating, surface them explicitly:

1. Set the signing secret before the first build — bash: gh secret set TAURI_SIGNING_PRIVATE_KEY < src-tauri/app.key; PowerShell: Get-Content src-tauri/app.key -Raw | gh secret set TAURI_SIGNING_PRIVATE_KEY; or the GitHub UI. Without it, CI signing fails (step 7).
2. Publish (un-draft) the first release — builds produce a draft; the updater resolves releases/latest, which ignores drafts, so updates never reach anyone until you un-draft it (gotcha #6).
3. Tag from a default-branch commit that already contains the corrected workflow — a tag-triggered run uses the workflow from the tagged commit, not the branch tip (gotcha #13). If you removed the template's tag-injection step, keep package.json equal to the pushed v* tag (step 6).

Gotchas (the non-obvious, hard-won ones)

What to expect

A typical multi-locale next-intl tool migrates in a single branch: React untouched, a ~3–10 MB exe (vs ~150 MB for Electron), fully offline, CI-only builds across Windows/macOS/Linux plus a portable exe. The frontend build verifies locally; Rust compiles in CI.