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:
bash
# 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):
json
{
"package": {
"productName": "my-app",
"version": "1.0.0"
},
"tauri": {
"bundle": { ... },
"allowlist": { ... }
}
}
After (v2):
json
{
"productName": "my-app",
"version": "1.0.0",
"mainBinaryName": "my-app",
"identifier": "com.example.myapp",
"app": { ... },
"bundle": { ... }
}
Key Renames
| v1 Path | v2 Path |
|---|
| (top-level) |
| (top-level) |
| |
| (top-level) |
| (top-level) |
| |
| |
| |
BREAKING: New Required Field
Add
matching your
- this is no longer automatic:
json
{
"productName": "My App",
"mainBinaryName": "My App"
}
Bundle Configuration Reorganization
Platform-specific bundle configs moved under their platform key:
Before:
json
{
"tauri": {
"bundle": {
"dmg": { ... },
"deb": { ... }
}
}
}
After:
json
{
"bundle": {
"macOS": {
"dmg": { ... }
},
"linux": {
"deb": { ... }
}
}
}
Updater Configuration
If using the app updater, add to bundle config:
json
{
"bundle": {
"createUpdaterArtifacts": "v1Compatible"
}
}
Use
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
src-tauri/capabilities/default.json:
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
command auto-generates capabilities from your v1 allowlist.
Cargo.toml Changes
Removed Features
These features no longer exist in v2:
reqwest-native-tls-vendored
New Features
- - Custom protocol request body parsing support
BREAKING: API Module Removal
The entire
module is removed. Functionality moved to plugins:
| v1 API | v2 Replacement |
|---|
| |
| |
| |
| functions | |
BREAKING: Rust API Changes
Removed APIs
| v1 | v2 Alternative |
|---|
| tauri-plugin-clipboard-manager
|
App::global_shortcut_manager
| tauri-plugin-global-shortcut
|
| |
| |
Renamed Types/Methods
| v1 | v2 |
|---|
| |
| Manager::get_webview_window
|
Menu API Changes
Before:
rust
use tauri::{Menu, CustomMenuItem};
let menu = Menu::new()
.add_item(CustomMenuItem::new("quit", "Quit"));
After:
rust
use tauri::menu::{MenuBuilder, MenuItemBuilder};
let menu = MenuBuilder::new(app)
.item(&MenuItemBuilder::with_id("quit", "Quit").build(app)?)
.build()?;
Tray API Changes
Before:
rust
use tauri::SystemTray;
SystemTray::new().with_menu(menu);
After:
rust
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/webviewWindow
|
Core API Reduction
The core
package now only includes:
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/clipboard
| @tauri-apps/plugin-clipboard-manager
|
| @tauri-apps/plugin-dialog
|
| |
@tauri-apps/api/global-shortcut
| @tauri-apps/plugin-global-shortcut
|
| |
@tauri-apps/api/notification
| @tauri-apps/plugin-notification
|
| |
| @tauri-apps/plugin-process
|
| |
| @tauri-apps/plugin-updater
|
Installing Plugins
bash
# JavaScript
npm install @tauri-apps/plugin-fs
# Rust (add to Cargo.toml)
cargo add tauri-plugin-fs
Register plugins in your Rust code:
rust
fn main() {
tauri::Builder::default()
.plugin(tauri_plugin_fs::init())
.run(tauri::generate_context!())
.expect("error running app");
}
BREAKING: File System Plugin Changes
BREAKING: Event System Changes
| v1 | v2 |
|---|
| Broadcasts to ALL listeners (behavior change) |
| N/A | - target specific event targets |
| |
BREAKING: Windows Origin URL
Production Windows apps now serve from
instead of
.
Impact: IndexedDB and cookies will reset unless you preserve the old behavior:
json
{
"app": {
"windows": [{
"useHttpsScheme": true
}]
}
}
BREAKING: Environment Variables
| v1 | v2 |
|---|
| TAURI_SIGNING_PRIVATE_KEY
|
| TAURI_SIGNING_PRIVATE_KEY_PASSWORD
|
| |
| Platform variables | Now prefixed |
Mobile Support Setup
To target mobile alongside desktop:
1. Update Cargo.toml:
toml
[lib]
name = "app_lib"
crate-type = ["staticlib", "cdylib", "rlib"]
2. Rename src/main.rs to src/lib.rs:
rust
#[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:
rust
fn main() {
app_lib::run();
}
V2 Beta to V2 Stable Migration
BREAKING: Core Permission Prefix
All core permissions now require the
prefix:
Before (beta):
json
{
"permissions": [
"path:default",
"event:default",
"window:default"
]
}
After (stable):
json
{
"permissions": [
"core:path:default",
"core:event:default",
"core:window:default"
]
}
Simplified alternative: Use
to include all default core permissions:
json
{
"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):
javascript
const mobile = !!/android|ios/.exec(process.env.TAURI_ENV_PLATFORM);
export default {
server: {
host: mobile ? '0.0.0.0' : false
}
};
After (stable):
javascript
const host = process.env.TAURI_DEV_HOST;
export default {
server: {
host: host || false
}
};
Remove dependency on the
NPM package if previously used.
iOS Device Development: Requires additional steps. Use:
bash
tauri ios dev --force-ip-prompt
Select the device's TUN address when prompted.
Migration Checklist
V1 to V2
V2 Beta to V2 Stable
Common Issues
| Issue | Solution |
|---|
| Permission denied errors | Check files for required permissions |
| IndexedDB/localStorage lost (Windows) | Set in window config |
| Plugin not found | Add to Cargo.toml, register with , install npm package |
| Mobile build fails | Verify section in Cargo.toml and with mobile entry point |