デスクトップアプリ（Electrobun）設計書

最終更新: 2026-08-27

1. 概要

MorningStatusApp デスクトップアプリ（Windows／macOS）のアーキテクチャ設計書。Next.js standalone サーバーを Electrobun でラップし、単一のネイティブアプリとして配布する仕組みを扱う。

この領域のドキュメントはこれまで docs/notes/DEVELOPMENT_NOTES.md の断片的な知見や README の変更履歴に散在しており、設計の全体像をまとめた文書が存在しなかった。Windows/macOS でディレクトリ構成が異なる点（§3）のような前提知識が実装者間で共有されず、バグ（#1535）を誘発したことを受けて本書を新設した（#73）。

ビルド・インストールの実行手順（コマンド）は デスクトップアプリのビルド手順 に分離しており、本書はアーキテクチャ・実装仕様（Why・How が本質的に変わらない部分）に特化する。

2. ビルドフロー概要

1. DESKTOP_MODE=1 bun run next build で Next.js standalone サーバー（.next/standalone/）を生成
2. bunx electrobun build で Electrobun アプリ（プラットフォーム別バイナリ）を生成
3. 1 の standalone サーバー一式を、2 の成果物（.app バンドル／インストーラ用ディレクトリ）の Resources 配下にコピー

具体的なコマンド・スクリプト（setup/build-macos.sh・setup/build-installer.ps1）は デスクトップアプリのビルド手順 を参照。

3. プラットフォーム別ディレクトリ構成の違い

インストール済みアプリのディレクトリ構成は、Windows と macOS で「実行バイナリの配置ディレクトリ名」が異なる。両者とも実行バイナリ配置ディレクトリと Resources が同階層にあるという点は共通しているが、ディレクトリ名（bin か MacOS か）が異なるため、パス解決ロジックはプラットフォームごとに個別の検証が必要になる。

実際のパス解決は desktop/src/bun/resolve-paths.ts の resolveBunExecutablePath(resourcesDir, platform) に集約している。index.js の配置ディレクトリ（Resources/app/bun 相当）を起点に、darwin なら ../MacOS/bun、それ以外（Windows）なら ../bin/bun.exe を返す。

備考: 旧実装（#1535）は、macOS でも Windows と同じ計算式（{resourcesDir}/../bin/bun 相当）で bun 実行ファイルのパスを求めていた。macOS 対応自体は #711 で追加されたが、インストール済み .app での実機起動検証が行われておらず、実在する Contents/MacOS/bun を参照できずに ENOENT で起動失敗していた。プラットフォーム別のパス解決ロジックを resolve-paths.ts に切り出し、darwin の場合のみ ../MacOS/bun を返すように修正して解消した。

4. 起動フロー（インストール済みアプリ）

1. launcher.exe（Windows）／MorningStatusApp（macOS）→ Electrobun ランチャーが起動し、bun/index.js（Worker）を起動する
2. Worker が resolveBunExecutablePath() で同梱 bun 実行ファイルのパスを解決する（プラットフォーム別、§3参照）
3. 前回起動時の自プロセス（main.js = このWorker自身）のPID（OS一時ディレクトリの morning-status-app-desktop-main.pid に記録、MAIN_LOCK_FILE）が生存していれば killStaleServer() で強制終了し、ロックファイルを削除したうえで自身のPIDを書き込む。server.js の有無に関わらず常に実行する（#1563）
4. 前回起動時のサーバー PID（OS 一時ディレクトリの morning-status-app-desktop-server.pid に記録、SERVER_LOCK_FILE）が生存していれば killStaleServer() で強制終了し、ロックファイルを削除する（#1561）
5. Resources/nextjs/standalone/server.js を検出し、同梱 bun で Next.js サーバーを子プロセス起動、そのプロセス PID をロックファイルに書き込む（writeLockedPid()）
6. waitForServer() がサーバーのポート応答をポーリングする。応答前にサーバープロセスが終了した場合は起動失敗として扱う
7. BrowserWindow で http://localhost:{port}（既定 3001）を表示する
8. WebView2 は初回描画時にスクロールバーを描画しないため、dom-ready イベント後にウィンドウサイズを ±1px 変化させて再描画を強制する

備考: 以前は上記6の待機処理がポートへの応答有無だけを起動成功の判定基準にしており、ウィンドウを閉じても process.on("exit") のクリーンアップを素通りしてサーバー子プロセスが残留することがあった。再ビルド・再インストール後に起動すると、新しいサーバーがポートの bind に失敗し、残留していた旧バージョンのサーバーにそのまま接続してしまい、再ビルドしても画面が更新されないバグがあった（#1561）。PID ロックファイルによる残留プロセスの検出・強制終了（上記4・5）と、起動確認時のプロセス終了検知（上記6）を追加して解消した。

5. プロセス終了時のクリーンアップ

• 正常終了: process.on("exit") および app.on("before-quit", ...)（Electrobun の app export）で、spawn した Next.js サーバー子プロセスを kill() する
• 異常終了（強制終了・クラッシュ等）への対策: 上記フックは異常終了時には発火しないため、サーバー子プロセス（server.js）は §4-4 のロックファイル方式で次回起動時に自己修復する（#1561）。main.js 自身（Electrobun ランタイム本体）についても、launcher.exe の異常終了時には上記フックが発火しないため、同じロックファイル方式（§4-3、MAIN_LOCK_FILE）で次回起動時に自己修復する（#1563）

備考: 以前は main.js 自身を保護する仕組みが無く、launcher.exe（Electrobun ランタイム本体、main.js を実行する bun.exe の親プロセス）が異常終了すると main.js が孤児プロセスとして残留していた。ウィンドウ（WebView2）は launcher.exe ではなく main.js 側が保持しているため、残留した main.js は操作可能な旧ウィンドウごと生存し続けていた。この状態でインストーラの上書きアップグレードを実行すると、ファイルにロックがかかり失敗する場合があった（#1563）。server.js と同じ自己ロックファイル方式を main.js 自身にも適用し解消した。

6. WebView のキャッシュ制御

デスクトップモードの Next.js レスポンスは next.config.ts の headers() で Cache-Control: no-store を付与し、Next.js の ISR が内部的に設定する Cache-Control（s-maxage／stale-while-revalidate 等）を上書きする。適用条件は以下の2点で、Web 版（Vercel）の ISR キャッシュ設計には影響させない。

• DESKTOP_MODE=1 かつ macOS 限定: WKWebView（macOS）でのディスクキャッシュ不具合は実機調査で再現・検証済みだが、WebView2（Windows）では同種の不具合が未確認。Windows は macOS よりインストール・アンインストールの検証回数が大幅に多いにもかかわらず再現報告がないため、根拠のないまま Windows にも同じ対策を適用するのは妥当でないと判断し、process.platform で macOS 限定にガードしている
• _next/static 配下は対象外: source: '/((?!_next/static).*)' により除外する。同ディレクトリはコンテンツハッシュ付きファイル名で無期限キャッシュしてよいため、no-store の対象に含める必要がない

備考: 以前は Web 版と同じ ISR キャッシュヘッダーをそのまま返しており、WKWebView（macOS）が stale-while-revalidate に従って HTML をディスクキャッシュしていた。このキャッシュは .app の再インストールでは消えないため（Electrobun の BrowserView にキャッシュを明示的にクリアする API が無い）、サーバー自体が新バージョンで起動できていても画面には反映されないケースがあった（#1561）。デスクトップモードはローカル単一ユーザー向けで CDN キャッシュの恩恵がなく、常に最新の内容を表示すべきであるため、no-store を強制することで解消した。当初は全ルート・全プラットフォームに適用していたが、_next/static 配下の静的アセットまで無効化対象に巻き込んでいた点と、WebView2（Windows）では不具合が未確認のまま対策を適用していた点を別PRのレビュー（#1562）で指摘され、上記の適用条件に絞り込んだ。

7. 同梱 Bun バイナリのバージョン管理

electrobun パッケージは、システムの bun upgrade とは独立して、自前で固定バージョンの Bun バイナリを同梱する仕組みを持つ。バージョンは desktop/electrobun.config.ts の build.bunVersion（現在: 1.4.0）で明示指定しており、上げる場合はこのフィールドを更新する必要がある。

8. バージョン管理（アプリ本体）

アプリのバージョンは目的の異なる3箇所で個別に管理されており、自動同期される仕組みはない。

Windows インストーラ／画面表示用のバージョン（root package.json）と、Electrobun アプリ本体のバージョン（desktop/ 配下）は異なる数値体系で運用されている。

9. リソース（アイコン）

アイコン素材は desktop/assets/ に配置する。

desktop/assets/
  icons8-コーヒーカップ-100.png  # ソース画像（Icons8）
  icon.ico                        # Windows 用（100px PNG から生成）
  icon.iconset/                   # macOS 用（sharp で各サイズ生成済み）
    icon_16x16.png
    icon_16x16@2x.png
    icon_32x32.png
    icon_32x32@2x.png
    icon_128x128.png
    icon_128x128@2x.png
    icon_256x256.png
    icon_256x256@2x.png
    icon_512x512.png

electrobun.config.ts の build.win.icon（assets/icon.ico）／build.mac.icons（assets/icon.iconset）でビルド時に埋め込む。

アイコンを差し替える場合

より高解像度のソース画像（512px 以上推奨）を入手したら、以下のスクリプトで再生成する。

# Windows（Bun）: icon.ico を再生成
bun -e "
const pngPath = 'desktop/assets/<新しい画像>.png';
const icoPath = 'desktop/assets/icon.ico';
const pngData = await Bun.file(pngPath).arrayBuffer();
const pngBytes = new Uint8Array(pngData);
const buf = new ArrayBuffer(6 + 16 + pngBytes.length);
const view = new DataView(buf);
view.setUint16(0, 0, true); view.setUint16(2, 1, true); view.setUint16(4, 1, true);
view.setUint8(6, 0); view.setUint8(7, 0); view.setUint8(8, 0); view.setUint8(9, 0);
view.setUint16(10, 1, true); view.setUint16(12, 32, true);
view.setUint32(14, pngBytes.length, true); view.setUint32(18, 22, true);
new Uint8Array(buf, 22).set(pngBytes);
await Bun.write(icoPath, buf);
"

# macOS: iconset を再生成（macOS 環境で実行）
mkdir -p desktop/assets/icon.iconset
sips -z 16 16   <ソース>.png --out desktop/assets/icon.iconset/icon_16x16.png
sips -z 32 32   <ソース>.png --out desktop/assets/icon.iconset/icon_16x16@2x.png
sips -z 32 32   <ソース>.png --out desktop/assets/icon.iconset/icon_32x32.png
sips -z 64 64   <ソース>.png --out desktop/assets/icon.iconset/icon_32x32@2x.png
sips -z 128 128 <ソース>.png --out desktop/assets/icon.iconset/icon_128x128.png
sips -z 256 256 <ソース>.png --out desktop/assets/icon.iconset/icon_128x128@2x.png
sips -z 256 256 <ソース>.png --out desktop/assets/icon.iconset/icon_256x256.png
sips -z 512 512 <ソース>.png --out desktop/assets/icon.iconset/icon_256x256@2x.png
sips -z 512 512 <ソース>.png --out desktop/assets/icon.iconset/icon_512x512.png
iconutil -c icns desktop/assets/icon.iconset  # .icns も生成される

既知の問題

Windows ビルド時、rcedit の依存解決に失敗し launcher.exe／bun.exe へのアイコン埋め込みが警告付きでスキップされる場合がある（Cannot find module '...\node_modules\rcedit\package.json'）。Electrobun が Bun のグローバルキャッシュルートから実行される際、ローカルの node_modules/rcedit を解決できないことが原因（#846）。Electrobun 1.18.1・1.18.4-beta.3 の時点では未解消。Electrobun 2.0.1（§10）で解消されるか確認する。

10. 今後の対応方針

Electrobun 2.0.1 への移行（#1548）

1.x → 2.0 はメジャーバージョンアップで、新ビルドツールチェーン「Hutch」中心の設計に刷新されている。

• desktop/package.json の electrobun 依存を 2.0.1 に更新する
• desktop/hutch.config.ts を新設し、packageManager: "bun" を明示する（既存パッケージマネージャーを継続するため）
• desktop/tsconfig.json に "extends": "./.hutch/devkit/tsconfig.json" を追加する
• メインプロセスランタイムは Bun のまま維持する（Cottontail への切り替えは行わない）
• desktop/electrobun.config.ts は現状 2.0 での廃止フィールド（build.targets／build.useAsar／build.cefVersion）を使用していないため変更不要と想定するが、npx electrobun config --env=stable のバリデーションで実際に確認する
• 完了条件: Windows・macOS 両方で electrobun dev／build／インストーラ（DMG）生成・実機インストール後の起動確認が完了すること。あわせて §9「既知の問題」の #846（アイコン埋め込みエラー）が解消されるかを確認する

改訂履歴