wails

できること

• Wails の前提条件（Go、Node/NPM、プラットフォーム依存関係）をセットアップして検証します
• wails init でプロジェクトを作成し、テンプレートやフレームワークを選択します
• wails dev を使った開発ワークフローを実行し、ライブリロードやブラウザーモードについて説明します
• wails build とプラットフォーム固有のフラグを使って、本番用バイナリをビルドします
• ランタイム API（ウィンドウ、メニュー、ダイアログ、イベント、ログ、ブラウザー、クリップボード、画面、ドラッグ＆ドロップ）を使用します
• 必要に応じて wails.json とアプリケーションオプションを設定します
• フロントエンドのスクリプト挿入ルールと外部開発サーバーの設定を適用します
• プラットフォーム固有のパッケージ化、署名、トラブルシューティングに関するガイドを使用します
• CLI、オプション、メニュー、プロジェクト設定、ランタイムのリファレンスを案内します

使う場面

Wails アプリの作成、ローカル開発、ビルドの問題、CLI の使用には、このスキルを使ってください。 プラットフォーム、テンプレート、または Wails のバージョンが不明な場合は、確認の質問をしてください。

ワークフロー

1. 対象の OS と Wails のバージョンを確認します。
2. 前提条件として、Go 1.21 以降、Node/NPM、プラットフォーム依存関係（xcode、WebView2、GTK/WebKit）を確認します。
3. 新しいアプリの場合は、テンプレートを選び、wails init -n <name> -t <template> を実行します。
4. 開発時は wails dev を使い、http://localhost:34115 のブラウザー開発サーバーについて説明します。
5. ビルド時は wails build を使います。新しいディストリビューションの Linux で必要な場合は、-tags webkit2_41 を追加します。
6. ランタイムを使用する場合は、Go のランタイムパッケージ github.com/wailsapp/wails/v2/pkg/runtime または JS の window.runtime を使います。
7. イベントには、Go と JS の連携に EventsOn、EventsOnce、EventsOnMultiple、EventsOff、EventsEmit を優先して使います。
8. 問題が発生した場合は、wails doctor を実行して不足している依存関係を解決します。

アーキテクチャ

• Wails は、WebView フロントエンドと共有ランタイムライブラリを備えた Go アプリです。
• Go のメソッドはバインドされ、自動生成された wailsjs モジュールを通じて JS に公開されます。
• ランタイムメソッドは、Go では runtime、JS では window.runtime を通じて利用できます。

主なコマンド

go install github.com/wailsapp/wails/v2/cmd/wails@latest
wails doctor
wails init -n myproject -t <template>
wails dev
wails build

CLI の概要

• wails init：-t でテンプレート（ローカルまたはリモートの GitHub URL）、-n で名前、-d でディレクトリ、-ide を指定します。
• wails dev：-assetdir、-wailsjsdir、-frontenddevserverurl、-browser、-loglevel を指定します。
• wails build：-platform、-tags、-obfuscated、-upx、-nsis、-devtools、-debug を指定します。
• wails generate module：開発モードを実行せずに wailsjs を再生成します。
• wails generate template：フロントエンドプロジェクトからテンプレートを作成するか、派生させます。

ランタイム API マップ

• イベント：EventsOn、EventsOff、EventsOnce、EventsOnMultiple、EventsEmit。
• ログ：LogTrace、LogDebug、LogInfo、LogWarning、LogError、LogFatal、LogSetLogLevel。
• ウィンドウ：タイトル、サイズ、位置、全画面表示／最大化／最小化、表示／非表示、再読み込み、JS の実行。
• ダイアログ：ファイルを開く／保存するダイアログ、メッセージダイアログ（Go のみ）。
• メニュー：アプリケーションメニューの設定／更新（Go のみ）。
• ブラウザー：システムブラウザーで URL を開きます。
• クリップボード：テキストの取得／設定。
• 画面：接続された画面の一覧を取得します。
• ドラッグ＆ドロップ：OnFileDrop、OnFileDropOff（EnableFileDrop が必要です）。

設定とオプション

• wails.json：フロントエンドのディレクトリ／ビルドスクリプト、assetdir、再読み込み対象のディレクトリ、開発サーバー URL、出力名、ビルドタグ、フック、情報／関連付け／プロトコル、バインディングの TS 生成。
• アプリオプション：ウィンドウサイズ、フレーム、起動状態、背景、常に最前面に表示、メニュー、ログ、コールバック、バインディング、単一インスタンスロック、ドラッグ＆ドロップ、デフォルトのコンテキストメニュー、不正検知。
• OS 固有のオプション：Windows（WebView2、テーマ、背景、ズーム）、Mac（タイトルバー、外観、透明度、概要）、Linux（アイコン、GPU ポリシー）。

フロントエンドの統合

• デフォルトのスクリプト挿入では、index.html に /wails/ipc.js と /wails/runtime.js を追加します。
• <meta name="wails-options" content="noautoinject"> を使うと自動挿入を無効にでき、手動で挿入できます。
• 外部開発サーバー（例：CRA）では、frontend:dev:watcher と frontend:dev:serverUrl を設定します。

ガイドの要点

• Angular：ng 用に frontend:build、frontend:install、frontend:dev:watcher、frontend:dev:serverUrl を設定します。
• ルーティング：ハッシュベースのルーティングを推奨します（Vue の hash、Angular の useHash、React の HashRouter、Svelte の SPA router）。
• フレームレス：Frameless: true を設定し、--wails-draggable:drag と --wails-draggable:no-drag を使用します。
• オーバースクロール：html { height: 100%; overflow: hidden; } でバウンスを無効にします。
• 動的アセット：フォールバック／動的コンテンツの配信には AssetServer.Handler を使用します（Vite v5 の警告に注意してください）。
• 難読化：wails build -obfuscated を使用し、必要に応じて -garbleargs を指定します。また、wailsjs バインディングを使用します。
• 単一インスタンスロック：UniqueId と OnSecondInstanceLaunch を設定した SingleInstanceLock を使用します。
• カスタムプロトコルとファイル関連付け：info.protocols／info.fileAssociations を定義し、プラットフォームごとの設定を行います。
• NSIS インストーラー：NSIS をインストールし、wails build -nsis でビルドします。
• Wails の master／PR でのローカル開発：クローンしたリポジトリから go install を実行し、go.mod で replace を使用します。
• Linux に関する注意：ディストリビューションのパッケージサポート、メディア用の GStreamer プラグイン、NixOS でのフォントサイズの回避策。
• IDE：-ide vscode または -ide goland を指定します。フロントエンドのビルドに合わせて VS Code のタスクを調整します。
• チュートリアル：Hello World と Dogs API で基本的な初期化／ビルド／開発の流れを確認できます。

手順別ガイド

Angular 開発サーバー

1. wails.json で frontend:build を npx ng build に、frontend:install を npm install に設定します。
2. frontend:dev:watcher に npx ng serve、frontend:dev:serverUrl に http://localhost:4200 を追加します。
3. wails dev を実行します。

SvelteKit の統合

1. wails init -n <name> -t svelte を実行します。
2. frontend/ を削除し、npx sv create frontend を実行します。
3. wails.json に "wailsjsdir": "./frontend/src/lib" を追加し、パッケージマネージャーのコマンドを更新します。
4. main.go の //go:embed all:frontend/dist を //go:embed all:frontend/build に変更します。
5. .gitignore の frontend/dist を frontend/build に変更します。
6. frontend/ で依存関係をインストールし、アダプターを @sveltejs/adapter-static に置き換えます。
7. src/routes/+layout.ts を追加し、export const prerender = true と export const ssr = false を記述します。
8. wails dev を実行します。

フレームレスウィンドウのドラッグ領域

1. options.App で Frameless: true を設定します。
2. コンテナーに --wails-draggable:drag を使用します。
3. 操作可能な要素に --wails-draggable:no-drag を使用します。
4. CSS 変数を使用できない場合は、options で CSSDragProperty と CSSDragValue を設定します。

動的アセット

1. options.App で AssetServer.Handler を設定します。
2. ハンドラーで存在しないアセットを配信するか、GET 以外のリクエストを処理します。
3. 認可チェックなしで任意のファイルシステムパスを公開しないでください。

難読化ビルド

1. wails build -obfuscated（必要に応じて -garbleargs）でビルドします。
2. フロントエンドからの呼び出しには、window.go の名前ではなく、生成された wailsjs バインディングを使用してください。

単一インスタンスロック

1. UUID の UniqueId を指定して SingleInstanceLock を追加します。
2. OnSecondInstanceLaunch を使って引数を処理し、ウィンドウを前面に表示します。
3. 2 番目のインスタンスからのデータは信頼できない入力として扱います。

カスタムプロトコル

1. wails.json に scheme、description、role を含む info.protocols を追加します。
2. macOS：Mac.OnUrlOpen を処理します。
3. Windows：NSIS インストーラーを使用し、コマンドライン引数を解析するか、単一インスタンスロックを使用します。
4. Linux：パッケージ化を通じて .desktop ファイルと mime エントリーを作成します（例：nfpm）。

ファイル関連付け

1. wails.json に ext、name、iconName、description、role を含む info.fileAssociations を追加します。
2. macOS：Mac.OnFileOpen を処理します。
3. Windows：NSIS インストーラーを使用し、引数を解析するか、単一インスタンスロックを使用します。
4. Linux：mime ファイル、デスクトップエントリー、アイコン、パッケージ用スクリプトを作成します。

NSIS インストーラー

1. NSIS をインストールします（scoop／winget／choco／brew）。
2. wails.json の情報を build/windows/installer に設定します。
3. wails build -nsis を実行し、build/bin の出力を使用します。

Wails master/PR を使ったローカル開発

1. github.com/wailsapp/wails をクローンし、対象のブランチ／PR をチェックアウトします。
2. cd v2/cmd/wails && go install を実行します。
3. アプリの go.mod に replace github.com/wailsapp/wails/v2 => <clonedir>/wails/v2 を追加します。
4. 元に戻すには、CLI を @latest から再インストールし、replace を削除します。

拡張ガイド

コード署名（Windows）

1. .pfx/.p12 証明書を Base64 エンコードし、GitHub Actions のシークレットとして保存します。
2. CI でアプリをビルドし、signtool.exe を /fd sha256 およびタイムスタンプサーバーとともに使用します。
3. Actions を使用する場合は、署名のステップが wails build の後に実行されるようにします。

コード署名（macOS）

1. Apple Developer 証明書（.p12）を書き出し、Base64 エンコードします。
2. 署名と公証には gon を使用します。build/darwin/gon-sign.json とエンタイトルメントを設定します。
3. Apple-Actions/import-codesign-certs@v1 を使って証明書を読み込み、その後 gon を実行します。

Mac App Store への提出

1. App ID、証明書、プロビジョニングプロファイル、App Store Connect のエントリーを作成します。
2. App Sandbox の設定を含む build/darwin/entitlements.plist を追加します。
3. wails build -platform darwin/universal でビルドと署名を行い、その後 codesign と productbuild を実行します。
4. Transporter 経由でアップロードし、App Store Connect でビルドを添付します。

GitHub Actions を使ったクロスプラットフォームビルド

1. linux/amd64、windows/amd64、darwin/universal のマトリックスを使用します。
2. Node と Go の依存関係をキャッシュします。必要に応じて NODE_OPTIONS=--max-old-space-size=4096 を設定します。
3. wails build（または dAppServer/wails-build-action）を実行し、build/bin/* をアップロードします。

WebView2 の戦略（Windows）

1. wails build -webview2 <download|embed|browser|error> を使用します。
2. ランタイムを固定する場合は、WebviewBrowserPath を設定し、ランタイムをバンドルします。
3. 管理者として実行する場合は、WebviewUserDataPath を共有の場所に設定します。

手動ビルドの手順（分解）

1. フロントエンドの依存関係をインストールします（-s が指定されている場合、または frontend:install がない場合を除く）。
2. フロントエンドをビルドします（-s が指定されている場合、または frontend:build がない場合を除く）。
3. アセット／アイコンを生成します（Windows では winicon と winres を使用します）。
4. Go をコンパイルします（開発時は -tags dev と -gcflags、本番時は -tags desktop,production を使用します）。
5. 必要に応じて UPX で圧縮します（-upx）。

テンプレート

1. wails generate template -name <name> でテンプレートのひな形を作成します。
2. 既存のフロントエンドを使う場合は、-frontend でパスを指定し、テンプレートファイルを更新します。
3. wails init -t <path> を実行してから wails build でテストします。
4. GitHub に公開し、Community Templates に提出します。

IDE のセットアップ

1. wails init -ide vscode または -ide goland を使用します。
2. VS Code の場合は、.vscode/tasks.json を更新してフロントエンドのインストール／ビルド手順を含めます。
3. Vue と Vetur を使用する場合は、frontend/ を指す vetur.config.js を追加します。

トラブルシューティングの要点

1. 画面が白くなる場合：//go:embed all:frontend/dist と frontend/dist 内のアセットを確認します。
2. macOS で画面が真っ白になる場合：Info.plist に NSAllowsLocalNetworking を追加します。
3. Windows のアイコンキャッシュ：%LOCALAPPDATA%/IconCache.db を削除します。
4. 可変長引数：スプレッド構文を使わず、配列をバックエンドに渡します。
5. バインディングで停止する場合：wails.Run() の後にアプリが終了することを確認します。
6. macOS のコンパイルエラー：Xcode CLI ツールを更新するか、ツールチェーンのパスを切り替えます。
7. WebView2 が見つからない場合：正しいアーキテクチャのランタイムをインストールします。

ルーティングのパターン

1. Vue：createWebHashHistory()。
2. Angular：RouterModule.forRoot(routes, { useHash: true })。
3. React：HashRouter。
4. Svelte：svelte-spa-router。

マウスボタン（フレームレスアプリ）

1. mousedown リスナーを使い、event.button を調べてボタンのインデックスを確認します。

NixOS のフォントサイズの不具合

1. devShell フックに XDG_DATA_DIRS と GIO_MODULE_DIR を追加します。

メモ

• Wails は、フロントエンドから呼び出すための Go バインディングと TypeScript モデルを生成します。
• プロジェクトの構成には、main.go、frontend/、build/、wails.json が含まれます。
• ランタイムメソッドには、OnStartup または OnDomReady から取得したコンテキストが必要です。
• Go または JavaScript から、オプションのデータペイロードとともにイベントを送信できます。
• 手動ビルドは、インストール → フロントエンドのビルド → アセットの生成 → コンパイル → 必要に応じて UPX の順に行います。
• Windows WebView2 は、-webview2 の戦略または固定ランタイムで対応できます。
• コード署名、Mac App Store への提出、GitHub Actions でのビルドにはガイドを使用してください。
• 詳細については、CLI、オプション、メニュー、プロジェクト設定、ランタイムのリファレンスを参照してください。