T-CREATOR

Tauri の設定ファイル(tauri.conf.json)完全ガイド

Tauri の設定ファイル(tauri.conf.json)完全ガイド

Tauri アプリケーション開発において、tauri.conf.jsonは心臓部とも言える重要な設定ファイルです。アプリの動作やビルド方法、セキュリティポリシーまで、すべての設定がこの 1 つのファイルに集約されています。

初めて Tauri に触れる方にとって、この設定ファイルの複雑さは時として開発の壁となってしまいます。しかし、適切な知識があれば、この設定ファイルは強力な開発ツールへと変貌するのです。

背景

Tauri アプリケーション開発の現状

現代のデスクトップアプリ開発では、Electron や Tauri といったクロスプラットフォームフレームワークが主流となっています。特に Tauri は軽量性とセキュリティの高さで注目を集めており、多くの開発者が採用を検討しているフレームワークです。

Web ブラウザエンジンをバンドルしない Tauri は、アプリサイズの大幅な削減を実現しています。従来の Electron アプリが数百 MB にも達する一方で、Tauri アプリは数 MB という驚異的な軽量性を誇ります。

このような Tauri の特徴を最大限活用するためには、設定ファイルの理解が不可欠となっているのです。

設定ファイルの役割と重要性

Tauri アプリケーションの設定ファイル tauri.conf.json は、アプリの全体的な動作を決定する重要な役割を担っています。

mermaidflowchart TB
    Config[tauri.conf.json] --> App[アプリケーション設定]
    Config --> Build[ビルド設定]
    Config --> Security[セキュリティ設定]
    Config --> Bundle[パッケージング設定]
    App --> Window[ウィンドウ表示]
    App --> Menu[メニューバー]
    Build --> Frontend[フロントエンド処理]
    Build --> Backend[バックエンド処理]
    Security --> CSP[コンテンツセキュリティポリシー]
    Security --> API[API制限]
    Bundle --> Installer[インストーラー作成]
    Bundle --> Icon[アイコン設定]

上記の図が示すように、設定ファイルはアプリケーションのあらゆる側面に影響を与えます。適切な設定により、パフォーマンスの向上、セキュリティの強化、ユーザー体験の改善が実現できるでしょう。

tauri.conf.json の位置づけ

プロジェクトルートに配置される tauri.conf.json は、Tauri アプリケーションの設計図とも言える存在です。このファイルは以下の特徴を持っています。

  • 一元管理: すべての設定が 1 つのファイルに集約
  • JSON 形式: 構造化されたデータ形式で管理しやすい
  • 型安全性: TypeScript での型チェックに対応
  • 環境対応: 開発・本番環境での設定切り替えが可能

課題

設定ファイル理解の難しさ

Tauri の設定ファイルは非常に多くの設定項目を含んでおり、初心者の方にとって理解が困難な場合があります。

主な困難点として以下が挙げられるでしょう。

  • 設定項目の多さ: 100 以上の設定可能な項目
  • 階層構造の複雑さ: 深くネストされた設定構造
  • 相互依存関係: 設定項目同士の依存関係が複雑
  • ドキュメント分散: 設定に関する情報が複数箇所に分散

開発効率への影響

設定ファイルを適切に理解していない場合、以下のような問題が発生し、開発効率の低下を招く可能性があります。

問題分類具体的な症状影響度
ビルドエラー設定ミスによるビルド失敗
動作不良期待通りに動作しない機能
セキュリティ脆弱性の混入リスク
パフォーマンス最適化不足による動作遅延

よくある設定ミス

開発現場で頻繁に遭遇する設定ミスをいくつか紹介します。これらのミスは、プロジェクトの進行を大幅に遅らせる原因となることがあります。

パス設定の間違い:

json{
  "build": {
    "distDir": "./build", // 正しくは "../build"
    "beforeBuildCommand": "npm run build"
  }
}

権限設定の不備:

json{
  "tauri": {
    "allowlist": {
      "all": true // セキュリティリスクが高い設定
    }
  }
}

これらのミスは、アプリケーションの品質や安全性に直接影響するため、注意深い設定が必要となります。

解決策

tauri.conf.json の基本構造

ファイル概要

Tauri の設定ファイルは、プロジェクトルートディレクトリの src-tauri フォルダ内に配置される tauri.conf.json ファイルです。このファイルは、Tauri アプリケーション全体の動作を制御する中央設定ファイルとして機能します。

json{
  "$schema": "..\\gen\\schemas\\config.schema.json",
  "build": {},
  "package": {},
  "tauri": {},
  "plugins": {}
}

JSON 形式と階層構造

設定ファイルは標準的な JSON 形式で記述され、以下のような階層構造を持っています。

mermaidgraph TD
    Root[tauri.conf.json] --> Build[build]
    Root --> Package[package]
    Root --> Tauri[tauri]
    Root --> Plugins[plugins]

    Build --> DistDir[distDir]
    Build --> DevPath[devPath]
    Build --> BeforeBuild[beforeBuildCommand]

    Tauri --> Bundle[bundle]
    Tauri --> Security[security]
    Tauri --> Windows[windows]

    Bundle --> Identifier[identifier]
    Bundle --> Icon[icon]
    Bundle --> Targets[targets]

この図が示すように、各設定項目は論理的にグループ化されており、関連する設定が階層的に整理されています。

主要セクションの紹介

設定ファイルは主に以下の 5 つのメインセクションで構成されます。

1. build セクション: フロントエンドビルドに関する設定 2. package セクション: パッケージ基本情報の設定 3. tauri セクション: Tauri コア機能の設定 4. plugins セクション: プラグインの設定 5. app セクション: アプリケーション固有の設定

重要な設定項目の詳細解説

app 設定(アプリケーション基本情報)

アプリケーションの基本的な情報を定義するセクションです。

json{
  "package": {
    "productName": "MyTauriApp",
    "version": "0.1.0"
  },
  "tauri": {
    "windows": [
      {
        "title": "My Tauri Application",
        "width": 1200,
        "height": 800,
        "resizable": true,
        "fullscreen": false
      }
    ]
  }
}

productName: アプリケーションの表示名を指定します。この名前はタイトルバーやタスクバーに表示されます。

version: アプリケーションのバージョン番号です。セマンティックバージョニング形式で記述することが推奨されます。

windows: ウィンドウの初期設定を配列形式で定義します。複数のウィンドウを持つアプリケーションの場合、それぞれの設定を記述できます。

build 設定(ビルド関連)

フロントエンドのビルドプロセスに関する重要な設定です。

json{
  "build": {
    "distDir": "../dist",
    "devPath": "http://localhost:3000",
    "beforeBuildCommand": "yarn build",
    "beforeDevCommand": "yarn dev"
  }
}

distDir: ビルドされたフロントエンドファイルの格納ディレクトリパスを指定します。

devPath: 開発時のフロントエンド開発サーバーの URL またはファイルパスです。

beforeBuildCommand: 本番ビルド前に実行するコマンドを指定します。通常はフロントエンドのビルドコマンドを設定します。

beforeDevCommand: 開発モード起動前に実行するコマンドです。開発サーバーの起動コマンドを設定することが多いでしょう。

tauri 設定(コア機能)

Tauri アプリケーションのコア機能に関する設定を行います。

json{
  "tauri": {
    "allowlist": {
      "all": false,
      "shell": {
        "all": false,
        "open": true
      },
      "dialog": {
        "all": false,
        "open": true,
        "save": true
      }
    },
    "security": {
      "csp": "default-src 'self' tauri:"
    }
  }
}

allowlist: フロントエンドからアクセス可能な Tauri API を制限する重要なセキュリティ設定です。

security: コンテンツセキュリティポリシー(CSP)などのセキュリティ関連設定を定義します。

bundle 設定(パッケージング)

アプリケーションのパッケージングとインストーラー作成に関する設定です。

json{
  "tauri": {
    "bundle": {
      "identifier": "com.example.myapp",
      "icon": [
        "icons/32x32.png",
        "icons/128x128.png",
        "icons/icon.icns",
        "icons/icon.ico"
      ],
      "targets": "all",
      "windows": {
        "wix": {
          "skipWebView": false
        }
      },
      "macOS": {
        "entitlements": null,
        "exceptionDomain": null
      }
    }
  }
}

identifier: アプリケーションの一意識別子です。逆ドメイン名形式で記述します。

icon: 各プラットフォームで使用するアイコンファイルを配列で指定します。

targets: ビルド対象プラットフォームを指定します。"all" を指定すると全プラットフォーム対応です。

security 設定(セキュリティ)

Tauri アプリケーションのセキュリティ設定は、アプリの安全性を確保する上で極めて重要です。

json{
  "tauri": {
    "security": {
      "csp": "default-src 'self' tauri: asset: https://fonts.gstatic.com; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com;",
      "devCsp": "default-src 'self' tauri: asset: http://localhost:3000 ws://localhost:3000; style-src 'self' 'unsafe-inline'; font-src 'self';"
    },
    "allowlist": {
      "all": false,
      "fs": {
        "all": false,
        "readFile": false,
        "writeFile": false
      }
    }
  }
}

csp: 本番環境でのコンテンツセキュリティポリシーです。XSS 攻撃などを防ぐために重要な設定となります。

devCsp: 開発環境専用の CSP 設定です。通常は本番より緩い設定になります。

実践的な設定例

開発環境向け設定

開発効率を重視した設定例をご紹介します。

json{
  "build": {
    "devPath": "http://localhost:3000",
    "beforeDevCommand": "yarn dev"
  },
  "tauri": {
    "security": {
      "devCsp": "default-src 'self' tauri: asset: http://localhost:3000 ws://localhost:3000; script-src 'self' 'unsafe-eval'; style-src 'self' 'unsafe-inline';"
    },
    "windows": [
      {
        "title": "My App [Development]",
        "width": 1200,
        "height": 800,
        "center": true,
        "resizable": true
      }
    ]
  }
}

開発環境では、ホットリロードや開発サーバーへの接続を許可する設定が重要です。CSP も開発に適した緩い設定にしています。

プロダクション向け設定

本番環境では、セキュリティとパフォーマンスを重視した設定が必要です。

json{
  "build": {
    "distDir": "../build",
    "beforeBuildCommand": "yarn build"
  },
  "tauri": {
    "security": {
      "csp": "default-src 'self' tauri:; script-src 'self'; style-src 'self' 'unsafe-inline';"
    },
    "allowlist": {
      "all": false,
      "dialog": {
        "open": true,
        "save": true
      },
      "fs": {
        "readFile": true,
        "scope": ["$DOCUMENT/**"]
      }
    },
    "windows": [
      {
        "title": "My Application",
        "width": 1024,
        "height": 768,
        "minWidth": 800,
        "minHeight": 600,
        "center": true
      }
    ]
  }
}

本番環境では、必要最小限の API 権限のみを許可し、厳格な CSP を適用してセキュリティを確保します。

クロスプラットフォーム対応

複数のプラットフォームに対応したアプリケーションの設定例です。

json{
  "tauri": {
    "bundle": {
      "identifier": "com.example.myapp",
      "targets": ["app", "msi", "deb", "appimage", "dmg"],
      "icon": [
        "icons/32x32.png",
        "icons/128x128.png",
        "icons/128x128@2x.png",
        "icons/icon.icns",
        "icons/icon.ico"
      ],
      "windows": {
        "certificateThumbprint": null,
        "digestAlgorithm": "sha256",
        "timestampUrl": ""
      },
      "macOS": {
        "frameworks": [],
        "minimumSystemVersion": "10.13",
        "license": ""
      },
      "deb": {
        "depends": []
      }
    }
  }
}

各プラットフォーム固有の設定も含めることで、全環境で最適な動作を実現できます。

具体例

基本的なアプリケーション設定

実際の開発現場でよく使用される、基本的なアプリケーション設定の完全な例をご紹介します。

json{
  "$schema": "../gen/schemas/config.schema.json",
  "build": {
    "beforeBuildCommand": "yarn build",
    "beforeDevCommand": "yarn dev",
    "devPath": "http://localhost:3000",
    "distDir": "../build",
    "withGlobalTauri": false
  },
  "package": {
    "productName": "TaskManager Pro",
    "version": "1.0.0"
  },
  "tauri": {
    "allowlist": {
      "all": false,
      "shell": {
        "all": false,
        "open": true
      },
      "dialog": {
        "all": false,
        "open": true,
        "save": true
      },
      "fs": {
        "all": false,
        "readFile": true,
        "writeFile": true,
        "scope": ["$APPDATA/taskmanager/**"]
      }
    },
    "bundle": {
      "identifier": "com.example.taskmanager",
      "icon": [
        "icons/32x32.png",
        "icons/128x128.png",
        "icons/128x128@2x.png",
        "icons/icon.icns",
        "icons/icon.ico"
      ],
      "targets": "all"
    },
    "security": {
      "csp": "default-src 'self' tauri:; style-src 'self' 'unsafe-inline';"
    },
    "windows": [
      {
        "fullscreen": false,
        "height": 800,
        "resizable": true,
        "title": "TaskManager Pro",
        "width": 1200,
        "center": true,
        "minWidth": 800,
        "minHeight": 600
      }
    ]
  }
}

この設定例では、タスク管理アプリケーションに必要な基本的な機能を設定しています。ファイルの読み書き権限を適切に制限し、セキュリティを確保しながら必要な機能を提供しているのがポイントです。

ウィンドウカスタマイズ例

ユーザー体験を向上させるためのウィンドウカスタマイズ設定をご紹介します。

json{
  "tauri": {
    "windows": [
      {
        "label": "main",
        "title": "メインウィンドウ",
        "width": 1400,
        "height": 900,
        "center": true,
        "resizable": true,
        "minimizable": true,
        "maximizable": true,
        "closable": true,
        "decorations": true,
        "alwaysOnTop": false,
        "skipTaskbar": false,
        "transparent": false,
        "titleBarStyle": "Visible"
      },
      {
        "label": "settings",
        "title": "設定",
        "width": 600,
        "height": 400,
        "center": true,
        "resizable": false,
        "minimizable": false,
        "maximizable": false,
        "parent": "main",
        "modal": true
      }
    ]
  }
}

メインウィンドウと設定ウィンドウの 2 つを定義し、それぞれに適切な属性を設定しています。設定ウィンドウはモーダルダイアログとして動作し、メインウィンドウの子ウィンドウとして表示されます。

アイコン・メニュー設定

アプリケーションの外観とメニュー構成の設定例です。

json{
  "tauri": {
    "bundle": {
      "icon": [
        "icons/32x32.png",
        "icons/128x128.png",
        "icons/128x128@2x.png",
        "icons/icon.icns",
        "icons/icon.ico"
      ]
    },
    "systemTray": {
      "iconPath": "icons/tray-icon.png",
      "iconAsTemplate": true,
      "menuOnLeftClick": false
    },
    "menu": [
      {
        "label": "ファイル",
        "submenu": [
          {
            "label": "新規作成",
            "accelerator": "CmdOrCtrl+N"
          },
          {
            "label": "開く",
            "accelerator": "CmdOrCtrl+O"
          },
          {
            "type": "Separator"
          },
          {
            "label": "終了",
            "accelerator": "CmdOrCtrl+Q",
            "role": "Quit"
          }
        ]
      },
      {
        "label": "編集",
        "submenu": [
          {
            "label": "元に戻す",
            "accelerator": "CmdOrCtrl+Z",
            "role": "Undo"
          },
          {
            "label": "やり直し",
            "accelerator": "CmdOrCtrl+Shift+Z",
            "role": "Redo"
          }
        ]
      }
    ]
  }
}

システムトレイアイコンとメニューバーの設定を行っています。日本語メニューとキーボードショートカットも適切に設定されていますね。

セキュリティ設定の実装

堅牢なセキュリティを実現するための詳細な設定例です。

json{
  "tauri": {
    "security": {
      "csp": "default-src 'self' tauri: asset:; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' asset: data:; font-src 'self';"
    },
    "allowlist": {
      "all": false,
      "fs": {
        "all": false,
        "readFile": true,
        "writeFile": true,
        "readDir": false,
        "copyFile": false,
        "createDir": true,
        "removeDir": false,
        "removeFile": true,
        "renameFile": false,
        "exists": true,
        "scope": ["$APPDATA/myapp/**", "$DOCUMENT/MyApp/**"]
      },
      "http": {
        "all": false,
        "request": true,
        "scope": ["https://api.example.com/**"]
      },
      "dialog": {
        "all": false,
        "open": true,
        "save": true,
        "message": false,
        "ask": false,
        "confirm": false
      },
      "notification": {
        "all": true
      }
    }
  }
}

この設定では、各 API 機能ごとに細かく権限を制御しています。ファイルシステムアクセスは特定のディレクトリに限定し、HTTP 通信も信頼できる API エンドポイントのみに制限しています。

ビルド最適化設定

パフォーマンスと配布サイズを最適化するための設定例をご紹介します。

json{
  "build": {
    "beforeBuildCommand": "yarn build --mode production",
    "beforeDevCommand": "yarn dev",
    "devPath": "http://localhost:3000",
    "distDir": "../dist",
    "withGlobalTauri": false
  },
  "tauri": {
    "bundle": {
      "identifier": "com.example.optimized-app",
      "targets": ["app", "msi", "deb", "appimage"],
      "resources": ["assets/**"],
      "externalBin": [],
      "windows": {
        "webviewInstallMode": {
          "type": "downloadBootstrapper"
        },
        "wix": {
          "skipWebView": false,
          "language": "ja-JP",
          "template": "template.wxs"
        }
      },
      "macOS": {
        "minimumSystemVersion": "10.15",
        "entitlements": "entitlements.plist"
      },
      "deb": {
        "depends": ["webkit2gtk-4.0"]
      }
    },
    "updater": {
      "active": true,
      "endpoints": [
        "https://update.example.com/{{target}}/{{arch}}/{{current_version}}"
      ],
      "dialog": true,
      "pubkey": "your-public-key-here"
    }
  }
}

この設定では、自動更新機能を含む本格的な配布用設定を行っています。各プラットフォームごとの最適化設定も含まれており、実際の製品リリースに対応できる内容となっています。

まとめ

設定のベストプラクティス

Tauri の設定ファイルを効果的に活用するために、以下のベストプラクティスを心がけましょう。

セキュリティファースト 最小権限の原則に従い、必要最小限の API アクセス権限のみを許可することが重要です。"all": false から始めて、必要な機能のみを個別に有効化していく方法が推奨されます。

環境ごとの設定分離 開発環境と本番環境で異なる設定が必要な場合は、環境変数や条件分岐を活用して適切に管理しましょう。特に CSP と API エンドポイントは環境ごとに適切に設定する必要があります。

継続的な見直し プロジェクトの進行とともに、設定も進化させていくことが大切です。新しい機能の追加や要件変更に応じて、設定ファイルも適切に更新していきましょう。

トラブルシューティング

よくある問題とその解決方法をご紹介します。

エラーパターン原因解決方法
ビルドが失敗するパス設定が不正確distDir と devPath を確認
API が動作しないallowlist で権限が制限必要な API を個別に許可
CSP エラーが発生厳格すぎるポリシー開発用 CSP を緩く設定
アイコンが表示されないファイルパスが間違いアイコンファイルの存在確認

デバッグのコツ 設定に問題がある場合は、まず開発者ツールのコンソールログを確認しましょう。CSP エラーや API 権限エラーは、ここに詳細な情報が表示されます。

継続的な学習のポイント

Tauri は活発に開発が続けられているフレームワークです。継続的な学習のために以下の点を意識してください。

公式ドキュメントの確認 新しいバージョンがリリースされた際は、必ず公式ドキュメントで変更点を確認しましょう。設定項目の追加や変更が頻繁に行われています。

コミュニティとの交流 GitHub の Issues や Discord コミュニティで、他の開発者の質問や解決方法を参考にすることで、効果的な設定パターンを学べるでしょう。

実際のプロジェクトでの実践 理論だけでなく、実際のプロジェクトで様々な設定を試してみることが最も効果的な学習方法です。小さなサンプルアプリから始めて、徐々に複雑な設定に挑戦していきましょう。

関連リンク

以下のリソースが、さらなる学習と開発に役立つでしょう。