プラグインをインストールして有効化する【Tauri v2】

Tauri のプラグインは、処理をする Rust のクレートと、それを JS から呼ぶ npm パッケージの組でできています。使うには、両方を入れ、Rust 側でアプリに登録し、capabilities で JS からの呼び出しを許可する、という 4 か所がそろっている必要があり、tauri add はこれをまとめて行います。何が変わるのか、手動で入れる手順、コミュニティ製の入れ方、欠けた箇所をエラーの文面から見分ける方法を説明します。

前提条件

Tauri 2.x のプロジェクトで、src-tauri/src/lib.rs にテンプレートどおり tauri::Builder::default() があること。例では OS Info プラグイン（os）を入れます。公式プラグインの名前は利用可能な公式プラグインを確認するの表を参照してください。

1. tauri add で入れる

npm run tauri add os

変わる場所	内容
`package.json`	`@tauri-apps/plugin-os` を追加
`src-tauri/Cargo.toml`	`tauri-plugin-os = "2"` を追加
`src-tauri/src/lib.rs`	`.plugin(tauri_plugin_os::init())` を追加
`src-tauri/capabilities/`	`os:default` を追加

npm: プロジェクトで使っているパッケージマネージャー（npm・pnpm・yarn など）で入れます。single-instance のように Rust だけで動くプラグインでは、npm パッケージと権限は追加されません。
Cargo.toml: デスクトップ専用のプラグインは、デスクトップ向けの節（2 章）に入ります。
lib.rs: tauri::Builder::default() の直後に差し込むので、後から入れたものほど上に並び、そのあと rustfmt でファイル全体が整形されます（--no-fmt で止められます）。登録の形はプラグインに合わせて選ばれますが、Single Instance は空のコールバック付き、Stronghold は todo!() 入り（そのまま使うと panic）で入るので、中身を書き換えます。
capabilities: 候補のファイルが複数あると、どれに足すかを聞かれます。デスクトップ専用のものは platforms を絞った desktop.json に書かれ、無ければ作られます。

tauri add がしないのは、tauri.conf.json の plugins での設定（CLI の引数の定義など）、モバイル向けの #[cfg(desktop)]、default に含まれない権限の追加です。

2. 手動で入れる (Rust)

lib.rs の形をテンプレートから変えている場合など、tauri add が使えないときは 4 か所を自分で書きます。

# Rust のクレート（src-tauri で実行）
cd src-tauri
cargo add tauri-plugin-os
cd ..
# JS のパッケージ（Rust だけで動くプラグインでは不要）
npm install @tauri-apps/plugin-os

デスクトップ専用のものは、Cargo.toml の次の節に手で書くのが確実です（cargo add --target でも書けますが、" を含む指定はシェルによって崩れやすいため）。

[target.'cfg(not(any(target_os = "android", target_os = "ios")))'.dependencies]
tauri-plugin-single-instance = "2"
tauri-plugin-window-state = "2"

登録は Builder につなぎます。プラグインは登録した順に初期化されるので、Single Instance は先頭に置きます。

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    let builder = tauri::Builder::default();

    // デスクトップ専用のものは cfg(desktop) で囲む。多重起動の防止は最初に登録する
    #[cfg(desktop)]
    let builder = builder
        .plugin(tauri_plugin_single_instance::init(|_app, _args, _cwd| {}))
        .plugin(tauri_plugin_window_state::Builder::new().build());

    let builder = builder
        .plugin(tauri_plugin_os::init()) // 設定を持たないものは init()
        .plugin(tauri_plugin_store::Builder::new().build()); // 設定を持つものは Builder から

    builder
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

tauri add で後から別のプラグインを足すと先頭に差し込まれるので、Single Instance が先頭のままか確かめます。権限は src-tauri/capabilities/default.json に書きます。<名前>:default がすべてを許可するとは限らず、os:default にはホスト名の取得（os:allow-hostname）が含まれません。中身は npm run tauri permission ls os で確かめられます。

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "Capability for the main window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "opener:default",
    "os:default",
    "os:allow-hostname"
  ]
}

3. フロントエンドから呼んで確かめる (TypeScript)

4 か所がそろったかは、呼んでみると分かります。platform() は同期、locale() と hostname() は非同期です（OS の種類・CPU アーキテクチャ・ホスト名を取得する）。

import { hostname, locale, platform } from '@tauri-apps/plugin-os';

// 開発ビルドで呼び、どこかが欠けていればエラーの文面を見る
export async function checkOsPlugin() {
  try {
    console.log('platform:', platform()); // Rust 側で登録していないと TypeError
    console.log('locale:', await locale()); // os:default で許可される
    console.log('hostname:', await hostname()); // os:allow-hostname が必要
  } catch (e) {
    console.error('os プラグインを呼べません:', e);
  }
}

コミュニティ製のプラグインを入れる

公式サイトのプラグイン一覧の後半や、crates.io の tauri-plugin- で始まるクレートから探します。tauri add <名前> がそのまま使えるのは、クレートが tauri-plugin-<名前>、npm パッケージが tauri-plugin-<名前>-api で、init() で登録するものだけです。それ以外は README の手順で 4 か所を手で書きます（--branch などで GitHub 上の版を指定するオプションは公式専用）。入れる前に次を確かめます。

依存している tauri が 2 系か（1 系用は Tauri 2 では使えません）
権限の名前と default の中身（npm run tauri permission ls <名前>）
更新が続いているか。capabilities が制限するのは JS からの呼び出しだけで、プラグインの Rust コードはアプリと同じ権限で動くので、中身を確かめてから入れます

動作確認

npm run tauri info の「Plugins」に tauri-plugin-os と @tauri-apps/plugin-os が同じバージョンで並べば、両方入っています。npm run tauri dev で checkOsPlugin() を呼ぶと、コンソールに次のように出ます。

platform: windows
locale: ja-JP
hostname: DESKTOP-AB12CD3

よくあるエラーと対処法

欠けている場所はエラーの文面で見分けられます（文面は開発ビルドのもの）。

「Cannot find module '@tauri-apps/plugin-os'」（tsc）や「Failed to resolve import」（Vite）: npm パッケージがありません。
ビルドが「Permission os:default not found, expected one of」で始まるエラーで止まる: capabilities に書いたプラグインのクレートが Cargo.toml にありません。権限を書いていなければ、呼び出し時に「os.locale not allowed. Plugin not found」になります。
「plugin os not found」、または platform() で __TAURI_OS_PLUGIN_INTERNALS__ が undefined という趣旨の TypeError: クレートはあるのに、lib.rs で .plugin() していません。
「os.hostname not allowed. Permissions associated with this command: os:allow-hostname」: 権限が足りません。リリースビルドでは「Command plugin:os|hostname not allowed by ACL」になります。
「… not allowed. Command not found」: npm パッケージの方が新しく、Rust 側に無いコマンドを呼んでいます。2.2 以降は両方の版番号が揃っているので、tauri info で同じ版にします（Tauri CLI を最新版にアップグレードする）。
tauri add で「Couldn't find」で始まり「you must enable the plugin in your Rust code manually」と続く警告: lib.rs に差し込む場所が見つかりませんでした。表示されたコードを自分で足します。

OS ごとの違いと注意点

iOS / Android: デスクトップ専用のプラグインを tauri add すると、クレートと権限はデスクトップ向けに限られますが、lib.rs の登録は条件なしです。モバイルもビルドするなら 2 章のように #[cfg(desktop)] で囲みます。
共通: 依存の書き方は Cargo.toml で Rust のパッケージを管理する、多重起動の防止は Single Instance プラグインで多重起動を防ぐを参照してください。

プラグインをインストールして有効化する