Tauri Plugins

Tauri v2 official plugins

Tauri v2 splits most APIs out of core into versioned plugins under tauri-apps/plugins-workspace. Every plugin ships three pieces you must wire together: a Rust crate (tauri-plugin-<name>), a JS package (@tauri-apps/plugin-<name>), and a set of permission identifiers that must be granted in a capability file. Skipping the capability grant is the single most common cause of "not allowed" errors at runtime.

Read this skill alongside tauri-security (capabilities + scopes) and tauri-setup (project layout). The five categories below cover every official plugin in the v2 docs.

How to add any plugin (3 steps)

1. Install both sides (run from project root):

   cd src-tauri && cargo add tauri-plugin-<name>
   bun add @tauri-apps/plugin-<name>     # or npm/pnpm/yarn
   

   Some mobile-capable plugins need cargo add --target 'cfg(any(target_os = "android", target_os = "ios"))' tauri-plugin-<name>.

2. Register in Rust — src-tauri/src/lib.rs:

   tauri::Builder::default()
       .plugin(tauri_plugin_<name>::init())
       .setup(|app| Ok(()))
       .run(tauri::generate_context!())
       .expect("error while running tauri application");
   

   A few plugins use a builder (Builder::default().build()) instead of init() — noted per-plugin below.

3. Grant permissions — src-tauri/capabilities/default.json:

   {
     "identifier": "default",
     "windows": ["main"],
     "permissions": [
       "core:default",
       "<plugin>:default",        // or finer-grained: "<plugin>:allow-<cmd>"
     ]
   }
   

   Most plugins ship <plugin>:default covering the common safe commands; anything destructive (write, execute, exit) requires opting in to a specific identifier.

See templates/lib.rs and templates/capabilities-plugins.json for a working multi-plugin setup.

Filesystem & data

fs — scoped filesystem access

Scopes are mandatory for anything outside the app's own data dir. Example fragment grants read access to $HOME/.config/myapp/**:

{ "identifier": "fs:allow-read-text-file",
  "allow": [{ "path": "$HOME/.config/myapp/**" }] }

store — JSON key-value persistence

sql — SQLite / MySQL / Postgres

stronghold — encrypted secrets vault (IOTA Stronghold)

persisted-scope — re-grant fs/asset scopes across restarts

upload — multipart file upload/download with progress

Shell & process

shell — spawn sidecars or whitelisted external commands

Sidecars must also be listed in tauri.conf.json → bundle.externalBin.

opener — open URLs / files with the OS default handler

process — exit/relaunch the app

single-instance — enforce one running instance

autostart — launch at OS login

cli — parse CLI args passed to the bundled binary

UI feedback

dialog — file pickers, message/confirm/ask dialogs

notification — OS notifications

clipboard-manager — read/write clipboard text & images

global-shortcut — system-wide hotkeys (desktop only)

Network

http — fetch-style HTTP client (no CORS, scoped)

websocket — outbound WebSocket client

localhost — serve the frontend over http://localhost:<port> instead of tauri://

Platform info

os — platform / arch / version / hostname

log — structured logging from JS + Rust to stdout/file/webview

Linking

deep-link — receive myapp://... URLs from OS

Common pitfalls

• Forgot the capability grant. Most "not allowed by ACL" / "plugin command X not allowed" errors come from registering the plugin in Rust but never adding <plugin>:default (or a finer permission) to a capability file. Check src-tauri/capabilities/*.json.
• shell:allow-execute without scope. The permission alone does nothing; you must list each allowed command + arg validator under "allow". Missing scope = silent no-op or rejected command.
• fs paths. Capability scopes use placeholders ($HOME, $APPDATA, $DOCUMENT, $DOWNLOAD, $RESOURCE, $TEMP), not literal paths. Globs are ** for recursive. Without a scope entry, every fs call outside the app data dir fails.
• Deep-link without manifest config. plugins.deep-link.desktop.schemes (and .mobile.schemes) in tauri.conf.json is required. macOS will silently ignore links until the bundle is rebuilt with the right CFBundleURLTypes; Android needs the intent filter regenerated.
• single-instance plugin order. Register it as the FIRST plugin on the builder — later plugins running in the duplicate process can corrupt state before the duplicate exits.
• Mobile-only vs desktop-only. global-shortcut, cli, single-instance, autostart, localhost are desktop-only. notification and deep-link need extra mobile setup.
• opener vs shell. "Open this file in Finder" / "open URL in browser" should use opener, not shell. The shell plugin's open is deprecated for that use case and pulls in the much more powerful (and more permission-hungry) execute machinery.
• Plugin name skew. The crate is tauri-plugin-clipboard-manager, the npm package is @tauri-apps/plugin-clipboard-manager, the JS API surface is clipboard-manager permissions — not clipboard. Same kind of dash-suffix exists for global-shortcut and single-instance.

Templates

• templates/lib.rs — tauri::Builder chain registering opener, dialog, fs, store, log, and notification.
• templates/capabilities-plugins.json — matching capability file with the right <plugin>:default grants plus scoped fs:allow-read-text-file on $APPCONFIG/**.