Impertio-Studio tauri-impl-migration
Quick Reference
Migration CLI Command
npx @tauri-apps/cli migrate
This auto-converts v1 allowlist entries to capability files, updates Cargo dependencies, and restructures configuration. ALWAYS run this first before manual migration.
Configuration Key Mapping (v1 to v2)
| Tauri v1 | Tauri v2 |
|---|---|
package.productName |
productName (top-level) |
package.version |
version (top-level) |
tauri |
app |
tauri.allowlist |
Removed -- replaced by capabilities/permissions |
tauri.bundle |
bundle (top-level) |
tauri.cli |
plugins.cli |
tauri.updater |
plugins.updater |
tauri.systemTray |
app.trayIcon |
tauri.allowlist.protocol.assetScope |
app.security.assetProtocol.scope |
tauri.pattern |
app.security.pattern |
build.distDir |
build.frontendDist |
build.devPath |
build.devUrl |
build.withGlobalTauri |
app.withGlobalTauri |
tauri.windows[].fileDropEnabled |
app.windows[].dragDropEnabled |
Critical Warnings
NEVER skip running npx @tauri-apps/cli migrate -- manual migration is error-prone and the CLI handles most conversions automatically.
NEVER forget to implement update UI -- Tauri v2 removed the automatic update dialog. Without explicit update checking code, users will NEVER receive updates.
NEVER use old import paths after migration -- @tauri-apps/api/tauri is now @tauri-apps/api/core; module-specific APIs moved to plugin packages.
NEVER use "v1Compatible" for createUpdaterArtifacts in new projects -- only use it when migrating existing installations from v1 updater.
ALWAYS restructure for mobile support if targeting mobile -- split main.rs into lib.rs + main.rs with #[cfg_attr(mobile, tauri::mobile_entry_point)].
ALWAYS add core permissions to capabilities -- v2 requires explicit permissions even for core features (windows, events, paths).
Rust API Changes
Type Renames
| Tauri v1 | Tauri v2 |
|---|---|
Window |
WebviewWindow |
WindowBuilder |
WebviewWindowBuilder |
WindowUrl |
WebviewUrl |
Manager::get_window() |
Manager::get_webview_window() |
Removed Modules (Now Plugins)
| v1 Module | v2 Replacement |
|---|---|
api::dialog |
tauri-plugin-dialog |
api::http |
tauri-plugin-http |
api::path |
Manager::path() methods |
api::process |
tauri-plugin-process |
api::shell |
tauri-plugin-shell |
Removed Manager Methods
| v1 Method | v2 Replacement |
|---|---|
App::clipboard_manager() |
tauri-plugin-clipboard-manager |
App::get_cli_matches() |
tauri-plugin-cli |
App::global_shortcut_manager() |
tauri-plugin-global-shortcut |
JavaScript API Changes
Module Renames
| Tauri v1 | Tauri v2 |
|---|---|
@tauri-apps/api/tauri |
@tauri-apps/api/core |
@tauri-apps/api/window |
@tauri-apps/api/webviewWindow |
Non-Core Modules Removed
All non-core modules removed from @tauri-apps/api. Install per-plugin packages:
| v1 Import | v2 Plugin Package |
|---|---|
@tauri-apps/api/dialog |
@tauri-apps/plugin-dialog |
@tauri-apps/api/fs |
@tauri-apps/plugin-fs |
@tauri-apps/api/http |
@tauri-apps/plugin-http |
@tauri-apps/api/shell |
@tauri-apps/plugin-shell |
@tauri-apps/api/notification |
@tauri-apps/plugin-notification |
@tauri-apps/api/clipboard |
@tauri-apps/plugin-clipboard-manager |
@tauri-apps/api/os |
@tauri-apps/plugin-os |
@tauri-apps/api/process |
@tauri-apps/plugin-process |
@tauri-apps/api/updater |
@tauri-apps/plugin-updater |
Event System Changes
| Aspect | Tauri v1 | Tauri v2 |
|---|---|---|
emit() |
Emits to specific window | Broadcasts to ALL listeners |
| Targeted emit | N/A | New emit_to() function |
| Global listen | listen_global() |
Renamed to listen_any() |
| Window listen | Receives all events | WebviewWindow.listen() only receives events for that specific window |
Menu System Overhaul
| Tauri v1 | Tauri v2 |
|---|---|
Menu |
MenuBuilder |
CustomMenuItem |
MenuItemBuilder |
Submenu |
SubmenuBuilder |
MenuItem (predefined) |
PredefinedMenuItem |
SystemTray |
TrayIconBuilder |
Builder::on_menu_event() |
App::on_menu_event() or AppHandle::on_menu_event() |
Feature Flag Changes
Removed flags:
reqwest-clientreqwest-native-tls-vendoredprocess-command-apishell-open-apiwindows7-compatupdaterlinux-protocol-headerssystem-tray
Added flags:
linux-protocol-body
Plugin Migration Table
| Feature | Cargo Crate | npm Package |
|---|---|---|
| Clipboard | tauri-plugin-clipboard-manager = "2" |
@tauri-apps/plugin-clipboard-manager |
| Dialogs | tauri-plugin-dialog = "2" |
@tauri-apps/plugin-dialog |
| File System | tauri-plugin-fs = "2" |
@tauri-apps/plugin-fs |
| Global Shortcuts | tauri-plugin-global-shortcut = "2" |
@tauri-apps/plugin-global-shortcut |
| HTTP | tauri-plugin-http = "2" |
@tauri-apps/plugin-http |
| Notifications | tauri-plugin-notification = "2" |
@tauri-apps/plugin-notification |
| OS Info | tauri-plugin-os = "2" |
@tauri-apps/plugin-os |
| Process | tauri-plugin-process = "2" |
@tauri-apps/plugin-process |
| Shell | tauri-plugin-shell = "2" |
@tauri-apps/plugin-shell |
| CLI Parsing | tauri-plugin-cli = "2" |
@tauri-apps/plugin-cli |
| Updater | tauri-plugin-updater = "2" |
@tauri-apps/plugin-updater |
Version Feature Matrix
| Feature | Tauri v1 | Tauri v2 |
|---|---|---|
| Desktop support | Yes | Yes |
| Mobile support | No | Yes (iOS + Android) |
| Permission system | Allowlist (boolean flags) | Capabilities + Permissions (fine-grained) |
| Plugin architecture | Monolithic API | Modular plugin packages |
| Menu API | Static builder | Dynamic builder pattern |
| Tray API | SystemTray |
TrayIconBuilder |
| Event broadcasting | Per-window default | Global broadcast default |
| IPC Channels | Not available | Channel<T> for streaming |
| Window types | Window only |
Window + Webview + WebviewWindow |
| Config format | Nested under tauri key |
Flat top-level keys |
| Update dialog | Built-in automatic | Must implement manually |
| Shell open | Built into shell module | Separate opener plugin |
| Binary data IPC | Not optimized | Response type bypasses JSON |
Mobile Restructuring
If targeting mobile, restructure the Rust entry point:
Before (v1 style, desktop only):
// src-tauri/src/main.rs
fn main() {
tauri::Builder::default()
.invoke_handler(tauri::generate_handler![])
.run(tauri::generate_context!())
.expect("error running app");
}
After (v2 style, desktop + mobile):
// src-tauri/src/lib.rs
#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
tauri::Builder::default()
.invoke_handler(tauri::generate_handler![])
.run(tauri::generate_context!())
.expect("error running app");
}
// src-tauri/src/main.rs (minimal)
fn main() {
app_lib::run();
}
Cargo.toml for mobile:
[lib]
name = "app_lib"
crate-type = ["staticlib", "cdylib", "rlib"]
Reference Links
- references/methods.md -- Complete v1-to-v2 API mapping tables
- references/examples.md -- Before/after migration code examples
- references/anti-patterns.md -- Migration mistakes with explanations