migrating-tauri-apps

Tauri Migration Guide

This skill covers migrating Tauri applications to v2 stable from either v1 or v2 beta.

Migration Paths

Source Version	Target	Complexity
Tauri v1.x	v2 stable	High - significant breaking changes
Tauri v2 beta	v2 stable	Low - minor breaking changes

---

Automated Migration

Both migration paths support automated migration via the Tauri CLI:

# Install latest CLI first
npm install @tauri-apps/cli@latest

# Run migration
npm run tauri migrate
# or: yarn tauri migrate | pnpm tauri migrate | cargo tauri migrate

IMPORTANT: The migrate command automates most tasks but is NOT a complete substitute for manual review. Always verify changes after running.

---

V1 to V2 Migration

Configuration File Changes

BREAKING: Top-Level Structure Changes

Before (v1):

{
  "package": {
    "productName": "my-app",
    "version": "1.0.0"
  },
  "tauri": {
    "bundle": { ... },
    "allowlist": { ... }
  }
}

After (v2):

{
  "productName": "my-app",
  "version": "1.0.0",
  "mainBinaryName": "my-app",
  "identifier": "com.example.myapp",
  "app": { ... },
  "bundle": { ... }
}

Key Renames

v1 Path	v2 Path
package.productName	productName (top-level)
package.version	version (top-level)
tauri	app
tauri.bundle	bundle (top-level)
tauri.bundle.identifier	identifier (top-level)
tauri.systemTray	app.trayIcon
build.distDir	frontendDist
build.devPath	devUrl

BREAKING: New Required Field

Add mainBinaryName matching your productName - this is no longer automatic:

{
  "productName": "My App",
  "mainBinaryName": "My App"
}

Bundle Configuration Reorganization

Platform-specific bundle configs moved under their platform key:

Before:

{
  "tauri": {
    "bundle": {
      "dmg": { ... },
      "deb": { ... }
    }
  }
}

After:

{
  "bundle": {
    "macOS": {
      "dmg": { ... }
    },
    "linux": {
      "deb": { ... }
    }
  }
}

Updater Configuration

If using the app updater, add to bundle config:

{
  "bundle": {
    "createUpdaterArtifacts": "v1Compatible"
  }
}

Use "v1Compatible" for existing distributions to maintain backward compatibility.

---

BREAKING: Allowlist Replaced with Capabilities

The v1 allowlist system is completely replaced with a capability-based ACL system.

Creating Capabilities

Create JSON files in src-tauri/capabilities/:

src-tauri/capabilities/default.json:

{
  "identifier": "default",
  "description": "Default capabilities for the main window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "shell:allow-open",
    "dialog:allow-open",
    "fs:allow-read-text-file"
  ]
}

The tauri migrate command auto-generates capabilities from your v1 allowlist.

---

Cargo.toml Changes

Removed Features

These features no longer exist in v2:

• reqwest-client
• reqwest-native-tls-vendored
• process-command-api
• shell-open-api
• windows7-compat
• updater
• system-tray

New Features

• linux-protocol-body - Custom protocol request body parsing support

BREAKING: API Module Removal

The entire api module is removed. Functionality moved to plugins:

v1 API	v2 Replacement
tauri::api::dialog	tauri-plugin-dialog
tauri::api::http	tauri-plugin-http
tauri::api::process	tauri-plugin-process
tauri::api::path functions	tauri::Manager::path

BREAKING: Rust API Changes

Removed APIs

v1	v2 Alternative
App::clipboard_manager	tauri-plugin-clipboard-manager
App::global_shortcut_manager	tauri-plugin-global-shortcut
App::get_cli_matches	tauri-plugin-cli
tauri::updater	tauri-plugin-updater

Renamed Types/Methods

v1	v2
Window	WebviewWindow
Manager::get_window	Manager::get_webview_window

Menu API Changes

Before:

use tauri::{Menu, CustomMenuItem};
let menu = Menu::new()
    .add_item(CustomMenuItem::new("quit", "Quit"));

After:

use tauri::menu::{MenuBuilder, MenuItemBuilder};
let menu = MenuBuilder::new(app)
    .item(&MenuItemBuilder::with_id("quit", "Quit").build(app)?)
    .build()?;

Tray API Changes

Before:

use tauri::SystemTray;
SystemTray::new().with_menu(menu);

After:

use tauri::tray::TrayIconBuilder;
TrayIconBuilder::new()
    .menu(&menu)
    .on_menu_event(|app, event| { ... })
    .on_tray_icon_event(|tray, event| { ... })
    .build(app)?;

---

BREAKING: JavaScript API Changes

Package Renames

v1	v2
@tauri-apps/api/tauri	@tauri-apps/api/core
@tauri-apps/api/window	@tauri-apps/api/webviewWindow

Core API Reduction

The core @tauri-apps/api package now only includes:

• core
• path
• event
• webviewWindow

All other APIs require plugin packages.

---

BREAKING: Plugin Migration

All formerly built-in APIs are now separate plugins:

v1 Import	v2 Plugin Package
@tauri-apps/api/cli	@tauri-apps/plugin-cli
@tauri-apps/api/clipboard	@tauri-apps/plugin-clipboard-manager
@tauri-apps/api/dialog	@tauri-apps/plugin-dialog
@tauri-apps/api/fs	@tauri-apps/plugin-fs
@tauri-apps/api/global-shortcut	@tauri-apps/plugin-global-shortcut
@tauri-apps/api/http	@tauri-apps/plugin-http
@tauri-apps/api/notification	@tauri-apps/plugin-notification
@tauri-apps/api/os	@tauri-apps/plugin-os
@tauri-apps/api/process	@tauri-apps/plugin-process
@tauri-apps/api/shell	@tauri-apps/plugin-shell
@tauri-apps/api/updater	@tauri-apps/plugin-updater

Installing Plugins

# JavaScript
npm install @tauri-apps/plugin-fs

# Rust (add to Cargo.toml)
cargo add tauri-plugin-fs

Register plugins in your Rust code:

fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_fs::init())
        .run(tauri::generate_context!())
        .expect("error running app");
}

BREAKING: File System Plugin Changes

Function renames in @tauri-apps/plugin-fs:

v1	v2
createDir	mkdir
readBinaryFile	readFile
writeBinaryFile	writeFile
removeDir	remove
removeFile	remove
renameFile	rename
Dir enum	BaseDirectory

BREAKING: Event System Changes

v1	v2
emit()	Broadcasts to ALL listeners (behavior change)
N/A	emit_to() - target specific event targets
listen_global	listen_any

BREAKING: Windows Origin URL

Production Windows apps now serve from http://tauri.localhost instead of https://.

Impact: IndexedDB and cookies will reset unless you preserve the old behavior:

{
  "app": {
    "windows": [{
      "useHttpsScheme": true
    }]
  }
}

BREAKING: Environment Variables

v1	v2
TAURI_PRIVATE_KEY	TAURI_SIGNING_PRIVATE_KEY
TAURI_KEY_PASSWORD	TAURI_SIGNING_PRIVATE_KEY_PASSWORD
TAURI_DEV_SERVER_PORT	TAURI_CLI_PORT
Platform variables	Now prefixed TAURI_ENV_

Mobile Support Setup

To target mobile alongside desktop:

1. Update Cargo.toml:

[lib]
name = "app_lib"
crate-type = ["staticlib", "cdylib", "rlib"]

2. Rename src/main.rs to src/lib.rs:

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .run(tauri::generate_context!())
        .expect("error running app");
}

3. Create new src/main.rs:

fn main() {
    app_lib::run();
}

---

V2 Beta to V2 Stable Migration

BREAKING: Core Permission Prefix

All core permissions now require the "core:" prefix:

Before (beta):

{
  "permissions": [
    "path:default",
    "event:default",
    "window:default"
  ]
}

After (stable):

{
  "permissions": [
    "core:path:default",
    "core:event:default",
    "core:window:default"
  ]
}

Simplified alternative: Use "core:default" to include all default core permissions:

{
  "permissions": ["core:default"]
}

---

BREAKING: Mobile Dev Server Configuration

The mobile development server no longer exposes across networks. Traffic tunnels directly from local machine to devices.

Before (beta):

const mobile = !!/android|ios/.exec(process.env.TAURI_ENV_PLATFORM);
export default {
  server: {
    host: mobile ? '0.0.0.0' : false
  }
};

After (stable):

const host = process.env.TAURI_DEV_HOST;
export default {
  server: {
    host: host || false
  }
};

Remove dependency on the internal-ip NPM package if previously used.

iOS Device Development: Requires additional steps. Use:

tauri ios dev --force-ip-prompt

Select the device's TUN address when prompted.

---

Migration Checklist

V1 to V2

• Run npm run tauri migrate
• Verify config structure changes (package -> top-level)
• Add mainBinaryName field
• Update bundle config structure
• Replace allowlist with capabilities
• Install required plugins
• Update Rust imports (Window -> WebviewWindow)
• Update JS imports (@tauri-apps/api/tauri -> core)
• Update FS function names if using fs plugin
• Update environment variable names
• Test event system behavior
• Verify Windows origin URL handling (IndexedDB/cookies)
• Update menu/tray code if used
• Remove deprecated Cargo features

V2 Beta to V2 Stable

• Run npm run tauri migrate
• Add core: prefix to permission identifiers (or use core:default)
• Update mobile dev server configuration
• Remove internal-ip package dependency if present
• Test iOS device development with --force-ip-prompt

---

Common Issues

Issue	Solution
Permission denied errors	Check src-tauri/capabilities/ files for required permissions
IndexedDB/localStorage lost (Windows)	Set useHttpsScheme: true in window config
Plugin not found	Add to Cargo.toml, register with .plugin(), install npm package
Mobile build fails	Verify [lib] section in Cargo.toml and src/lib.rs with mobile entry point