Upgrade from Tauri 1.0
This guide walks you through upgrading your Tauri 1.0 application to Tauri 2.0.
The mobile interface of Tauri requires your project to output a shared library. If you are targetting mobile for your existing application, you must change your crate to produce that kind of artifact along with the desktop executable.
- Change the Cargo manifest to produce the library. Append the following block:
-
Rename
src-tauri/src/main.rs
tosrc-tauri/src/lib.rs
. This file will be shared by both desktop and mobile targets. -
Rename the
main
function header inlib.rs
to the following:
The tauri::mobile_entry_point
macro prepares your function to be executed on mobile.
- Recreate the
main.rs
file calling the shared run function:
The Tauri v2 CLI includes a migrate
command that automates most of the process and helps you finish the migration:
Learn more about the migrate
command in the Command Line Interface reference
Below is a summary of the changes from Tauri 1.0 to Tauri 2.0:
package > productName
andpackage > version
moved to top-level field.package
removed.tauri
key renamed toapp
.tauri > allowlist
removed. Refer to Migrate Permissions.tauri > allowlist > protocol > assetScope
moved toapp > security > assetProtocol > scope
.tauri > cli
moved toplugins > cli
.tauri > windows > fileDropEnabled
renamed toapp > windows > dragDropEnabled
.tauri > updater > active
removed.tauri > updater > dialog
removed.tauri > updater
moved toplugins > updater
.tauri > systemTray
renamed toapp > trayIcon
.tauri > pattern
moved toapp > security > pattern
.tauri > bundle
moved top-level.tauri > bundle > dmg
moved tobundle > macOS > dmg
tauri > bundle > deb
moved tobundle > linux > deb
tauri > bundle > appimage
moved tobundle > linux > appimage
tauri > bundle > macOS > license
removed, usebundle > licenseFile
instead.tauri > bundle > windows > wix > license
removed, usebundle > licenseFile
instead.tauri > bundle > windows > nsis > license
removed, usebundle > licenseFile
instead.build > withGlobalTauri
moved toapp > withGlobalTauri
.build > distDir
renamed tofrontendDist
.build > devPath
renamed todevUrl
.
Tauri 2.0 Configuration API reference
- linux-protocol-body: Enables custom protocol request body parsing, allowing the IPC to use it. Requires webkit2gtk 2.40.
- reqwest-client: reqwest is now the only supported client.
- reqwest-native-tls-vendored: use
native-tls-vendored
instead. - process-command-api: use the
shell
plugin instead (see instructions in the following section). - shell-open-api: use the
shell
plugin instead (see instructions in the following section). - windows7-compat: moved to the
notification
plugin. - updater: Updater is now a plugin.
- linux-protocol-headers: Now enabled by default since we upgraded our minimum webkit2gtk version.
- system-tray: renamed to
tray-icon
.
api
module removed. Each API module can be found in a Tauri plugin.api::dialog
module removed. Usetauri-plugin-dialog
instead. Migrationapi::file
module removed. Use Rust’sstd::fs
instead.api::http
module removed. Usetauri-plugin-http
instead. Migrationapi::ip
module rewritten and moved totauri::ipc
. Check out the new APIs, speciallytauri::ipc::Channel
.api::path
module functions andtauri::PathResolved
moved totauri::Manager::path
. Migrationapi::process::Command
,tauri::api::shell
andtauri::Manager::shell_scope
APIs removed. Usetauri-plugin-shell
instead. Migrationapi::process::current_binary
andtauri::api::process::restart
moved totauri::process
.api::version
module has been removed. Use the semver crate instead.App::clipboard_manager
andAppHandle::clipboard_manager
removed. Usetauri-plugin-clipboard
instead. MigrationApp::get_cli_matches
removed. Usetauri-plugin-cli
instead. MigrationApp::global_shortcut_manager
andAppHandle::global_shortcut_manager
removed. Usetauri-plugin-global-shortcut
instead. MigrationManager::fs_scope
removed. The file system scope can be accessed viatauri_plugin_fs::FsExt
.Plugin::PluginApi
now receives a plugin configuration as a second argument.Plugin::setup_with_config
removed. Use the updatedtauri::Plugin::PluginApi
instead.scope::ipc::RemoteDomainAccessScope::enable_tauri_api
andscope::ipc::RemoteDomainAccessScope::enables_tauri_api
removed. Enable each core plugin individually viascope::ipc::RemoteDomainAccessScope::add_plugin
instead.scope::IpcScope
removed, usescope::ipc::Scope
instead.scope::IpcScope
removed, usescope::ipc::Scope
instead.scope::FsScope
,scope::GlobPattern
andscope::FsScopeEvent
removed, usescope::fs::Scope
,scope::fs::Pattern
andscope::fs::Event
respectively.updater
module removed. Usetauri-plugin-updater
instead. MigrationEnv.args
field has been removed, useEnv.args_os
field instead.Menu
,MenuEvent
,CustomMenuItem
,Submenu
,WindowMenuEvent
,MenuItem
andBuilder::on_menu_event
APIs removed. MigrationSystemTray
,SystemTrayHandle
,SystemTrayMenu
,SystemTrayMenuItemHandle
,SystemTraySubmenu
,MenuEntry
andSystemTrayMenuItem
APIs removed. Migration
The @tauri-apps/api
package no longer provides non-core modules. Only the previous tauri
(now core
), path
, event
and window
modules are exported. All others have been moved to plugins.
@tauri-apps/api/tauri
module renamed to@tauri-apps/api/core
. Migration@tauri-apps/api/cli
module removed. Use@tauri-apps/plugin-cli
instead. Migration@tauri-apps/api/clipboard
module removed. Use@tauri-apps/plugin-clipboard
instead. Migration@tauri-apps/api/dialog
module removed. Use@tauri-apps/plugin-dialog
instead. Migration@tauri-apps/api/fs
module removed. Use@tauri-apps/plugin-fs
instead. Migration@tauri-apps/api/global-shortcut
module removed. Use@tauri-apps/plugin-global-shortcut
instead. Migration@tauri-apps/api/http
module removed. Use@tauri-apps/plugin-http
instead. Migration@tauri-apps/api/os
module removed. Use@tauri-apps/plugin-os
instead. Migration@tauri-apps/api/notification
module removed. Use@tauri-apps/plugin-notification
instead. Migration@tauri-apps/api/process
module removed. Use@tauri-apps/plugin-process
instead. Migration@tauri-apps/api/shell
module removed. Use@tauri-apps/plugin-shell
instead. Migration@tauri-apps/api/updater
module removed. Use@tauri-apps/plugin-updater
instead Migration@tauri-apps/api/window
module renamed to@tauri-apps/api/webviewWindow
. Migration
Most of the environment variables read and written by the Tauri CLI were renamed for consistency and prevention of mistakes:
TAURI_PRIVATE_KEY
->TAURI_SIGNING_PRIVATE_KEY
TAURI_KEY_PASSWORD
->TAURI_SIGNING_PRIVATE_KEY_PASSWORD
TAURI_SKIP_DEVSERVER_CHECK
->TAURI_CLI_NO_DEV_SERVER_WAIT
TAURI_DEV_SERVER_PORT
->TAURI_CLI_PORT
TAURI_PATH_DEPTH
->TAURI_CLI_CONFIG_DEPTH
TAURI_FIPS_COMPLIANT
->TAURI_BUNDLER_WIX_FIPS_COMPLIANT
TAURI_DEV_WATCHER_IGNORE_FILE
->TAURI_CLI_WATCHER_IGNORE_FILENAME
TAURI_TRAY
->TAURI_LINUX_AYATANA_APPINDICATOR
TAURI_APPLE_DEVELOPMENT_TEAM
->APPLE_DEVELOPMENT_TEAM
TAURI_PLATFORM
->TAURI_ENV_PLATFORM
TAURI_ARCH
->TAURI_ENV_ARCH
TAURI_FAMILY
->TAURI_ENV_FAMILY
TAURI_PLATFORM_VERSION
->TAURI_ENV_PLATFORM_VERSION
TAURI_PLATFORM_TYPE
->TAURI_ENV_PLATFORM_TYPE
TAURI_DEBUG
->TAURI_ENV_DEBUG
The event system was redesigned to be easier to use. Instead of relying on the source of the event, it now has a simpler implementation that relies on event targets.
- The
emit
function now emits the event to all event listeners - Added a new
emit_to
function to trigger an event to a specific target emit_filter
now filters based onEventTarget
instead of a window.- Renamed
listen_global
tolisten_any
. It now listens to all events regardless of their filters and targets.
Tauri v2 introduces multiwebview support currently behind an unstable
feature flag.
In order to support it, we renamed the Rust Window
type to WebviewWindow
and the Manager get_window
function to get_webview_window
.
The WebviewWindow
JS API type is now re-exported from @tauri-apps/api/webviewWindow
instead of @tauri-apps/api/window
.
Common scenarios you may encounter when migrating your Tauri 1.0 app to Tauri 2.0.
The @tauri-apps/api/tauri
module was renamed to @tauri-apps/api/core
.
Simply rename the module import:
The Rust App::get_cli_matches
JavaScript @tauri-apps/api/cli
APIs have been removed. Use the @tauri-apps/plugin-cli
plugin instead:
- Add to cargo dependencies:
- Use in JavaScript or Rust project:
The Rust App::clipboard_manager
and AppHandle::clipboard_manager
and JavaScript @tauri-apps/api/clipboard
APIs have been removed. Use the @tauri-apps/plugin-clipboard-manager
plugin instead:
The Rust tauri::api::dialog
JavaScript @tauri-apps/api/dialog
APIs have been removed. Use the @tauri-apps/plugin-dialog
plugin instead:
- Add to cargo dependencies:
- Use in JavaScript or Rust project:
The Rust App::get_cli_matches
JavaScript @tauri-apps/api/fs
APIs have been removed. Use the std::fs
for Rust and @tauri-apps/plugin-fs
plugin for JavaScript instead:
- Add to cargo dependencies:
- Use in JavaScript or Rust project:
Some functions and types have been renamed or removed:
Dir
enum alias removed, useBaseDirectory
.FileEntry
,FsBinaryFileOption
,FsDirOptions
,FsOptions
,FsTextFileOption
andBinaryFileContents
interfaces and type aliases have been removed and replaced with new interfaces suited for each function.createDir
renamed tomkdir
.readBinaryFile
renamed toreadFile
.removeDir
removed and replaced withremove
.removeFile
removed and replaced withremove
.renameFile
removed and replaced withrename
.writeBinaryFile
renamed towriteFile
.
Use the Rust std::fs
functions.
The Rust App::global_shortcut_manager
and AppHandle::global_shortcut_manager
and JavaScript @tauri-apps/api/global-shortcut
APIs have been removed. Use the @tauri-apps/plugin-global-shortcut
plugin instead:
- Add to cargo dependencies:
- Use in JavaScript or Rust project:
The Rust tauri::api::http
JavaScript @tauri-apps/api/http
APIs have been removed. Use the @tauri-apps/plugin-http
plugin instead:
- Add to cargo dependencies:
- Use in JavaScript or Rust project:
The HTTP plugin re-exports reqwest so you can check out their documentation for more information.
The Rust tauri::api::notification
JavaScript @tauri-apps/api/notification
APIs have been removed. Use the @tauri-apps/plugin-notification
plugin instead:
- Add to cargo dependencies:
- Use in JavaScript or Rust project:
The Rust Menu
APIs were moved to the tauri::menu
module and refactored to use the muda crate.
Use tauri::menu::MenuBuilder
instead of tauri::Menu
. Note that its constructor takes a Manager instance (one of App
, AppHandle
or WebviewWindow
) as an argument:
Use tauri::menu::PredefinedMenuItem
instead of tauri::MenuItem
:
Use tauri::menu::MenuItemBuilder
instead of tauri::CustomMenuItem
:
Use tauri::menu::SubmenuBuilder
instead of tauri::Submenu
:
tauri::Builder::menu
now takes a closure because the menu needs a Manager instance to be built. See the documentation for more information.
The Rust tauri::Builder::on_menu_event
API was removed. Use tauri::App::on_menu_event
or tauri::AppHandle::on_menu_event
instead:
Note that there are two ways to check which menu item was selected: move the item to the event handler closure and compare IDs, or define a custom ID for the item through the with_id
constructor and use that ID string to compare.
The Rust tauri::api::os
JavaScript @tauri-apps/api/os
APIs have been removed. Use the @tauri-apps/plugin-os
plugin instead:
- Add to cargo dependencies:
- Use in JavaScript or Rust project:
The Rust tauri::api::process
JavaScript @tauri-apps/api/process
APIs have been removed. Use the @tauri-apps/plugin-process
plugin instead:
- Add to cargo dependencies:
- Use in JavaScript or Rust project:
The Rust tauri::api::shell
JavaScript @tauri-apps/api/shell
APIs have been removed. Use the @tauri-apps/plugin-shell
plugin instead:
- Add to cargo dependencies:
- Use in JavaScript or Rust project:
- Open an URL
- Spawn a child process and retrieve the status code
- Spawn a child process and capture its output
- Spawn a child process and read its events asynchronously:
The Rust SystemTray
APIs were renamed to TrayIcon
for consistency. The new APIs can be found in the Rust tray
module.
Use tauri::tray::TrayIconBuilder
instead of tauri::SystemTray
:
See TrayIconBuilder for more information.
Use tauri::menu::Menu
instead of tauri::SystemTrayMenu
, tauri::menu::Submenu
instead of tauri::SystemTraySubmenu
and tauri::menu::PredefinedMenuItem
instead of tauri::SystemTrayMenuItem
. Migration
tauri::SystemTray::on_event
have been split into tauri::tray::TrayIconBuilder::on_menu_event
and tauri::tray::TrayIconBuilder::on_tray_icon_event
:
The built-in dialog with an automatic update check was removed, use the Rust and JS APIs to check for and install updates instead.
The Rust tauri::updater
and JavaScript @tauri-apps/api-updater
APIs have been removed. To set a custom updater target with the @tauri-apps/plugin-updater
:
- Add to cargo dependencies:
- Use in JavaScript of Rust project:
To check for updates:
To set a custom updater target:
The Rust tauri::api::path
module functions and tauri::PathResolver
have been moved to tauri::Manager::path
:
On the Rust side, Window
was renamed to WebviewWindow
and its builder WindowBuilder
is now named WebviewWindowBuilder
.
Additionally, the Manager::get_window
function was renamed to get_webview_window
and
the window’s parent_window
API was renamed to parent_raw
to support a high level window parent API.
On the JavaScript side, the WebviewWindow
class is now exported in the @tauri-apps/api/webviewWindow
path.
The onMenuClicked
function was removed, you can intercept menu events when creating a menu in JavaScript instead.
In Tauri v1, the external binaries and their arguments were defined in the allowlist. In v2, use the new permissions system. Read Migrate Permissions for more information.
On the JavaScript side, make sure you Migrate to Shell Plugin.
On the Rust side, tauri::api::process
API has been removed. Use tauri_plugin_shell::ShellExt
and tauri_plugin_shell::process::CommandEvent
APIs instead. Read the Embedding External Binaries guide to see how.
The “process-command-api” features flag has been removed in v2. So running the external binaries does not require this feature to be defined in the Tauri config anymore.
The v1 allowlist have been rewritten to a completely new system for permissions that works for individual plugins and is much more configurable for multiwindow and remote URL support. This new system works like an access control list (ACL) where you can allow or deny commands, allocate permissions to a specific set of windows and domains, and define access scopes.
To enable permissions for your app, you must create capability files inside the src-tauri/capabilities
folder, and Tauri will automatically configure everything else for you.
The migrate
CLI command automatically parses your v1 allowlist and generates the associated capability file.
To learn more about permissions and capabilities, see the documentation.
© 2024 Tauri Contributors. CC-BY / MIT