ローカル開発

このガイドでは、Elftia のローカル開発環境を素早く構築してコーディングを始める方法を説明します。

前提条件

Node.js

このプロジェクトには Node.js v24 が必要です（プロジェクトルートの .nvmrc を参照）。バージョン管理には nvm または fnm の使用を推奨します：

nvm install
nvm use

ネイティブビルドツール

このプロジェクトは better-sqlite3 などのネイティブ Node.js モジュールに依存しており、C/C++ コンパイル環境が必要です：

プラットフォーム	必要なツール	インストール方法
Windows	Visual Studio Build Tools 2022	npm install -g windows-build-tools または VS サイト からインストール
macOS	Xcode Command Line Tools	xcode-select --install
Linux	build-essential, python3	sudo apt install build-essential python3（Debian/Ubuntu）

その他の依存関係

• Git >= 2.30
• ripgrep (rg) — postinstall スクリプトによって自動的にダウンロードされます。または手動でインストールしてください

---

プロジェクトの初期化

# 1. リポジトリをクローン
git clone <repo-url> elftia
cd elftia

# 2. 依存関係のインストール
npm install

npm install によって実行される postinstall スクリプトは、次の処理を自動的に行います：

• ネイティブモジュール（better-sqlite3、node-pty など）を現在の Electron バージョンに合わせて再コンパイル
• プラットフォーム固有の ripgrep バイナリをダウンロード

# 3. 環境変数ファイルを作成
cp .env.example .env

.env を編集して API キーやその他の設定を入力してください。

---

開発モードの起動

npm run dev

electron-vite dev が起動し、3 つのターゲットのコード変更を同時に監視します：

ターゲット	ディレクトリ	ホットリロード
メインプロセス	packages/desktop/app/main/	メインプロセスを再起動
プリロードスクリプト	packages/desktop/app/preload/	メインプロセスを再起動
レンダラー	packages/renderer/src/	Vite HMR（ポート 5375）

ヒント

初回起動時にネイティブモジュールエラーが発生した場合は、npm run rebuild を実行して再コンパイルを試してください。

---

すべての開発コマンド

コマンド	説明
npm run dev	Electron + Vite 開発モードを起動（メイン + プリロード + レンダラー）
npm run dev:web	レンダラーのみを起動（ウェブモード、Electron なし）
npm run dev:server	Fastify ウェブサーバーを起動（オプション）
npm run build	全パッケージをビルド（レンダラー + デスクトップ）
npm run build:renderer	フロントエンドのみをビルド（Vite プロダクションモード）
npm run build:desktop	Electron メインプロセスのみをビルド（tsup）
npm run build:official	オフィシャルリリースをビルド（署名付き）
npm run build:steam	Steam バージョンをビルド
npm run lint	ESLint + TypeScript 型チェックを実行
npm run lint:eslint	ESLint のみを実行
npm run typecheck	TypeScript コンパイルチェックのみを実行
npm run test	Vitest テストを実行
npm run format	全コードを Prettier でフォーマット
npm run format:file <path>	単一ファイルを Prettier でフォーマット
npm run verify:build	ビルド成果物のサイズを検証（4 つの主要指標）
npm run analyze:build	バンドル構成を分析（チャンク統計）

---

デバッグ

メインプロセスのデバッグ

方法 1：--inspect フラグ

# package.json の dev スクリプトに --inspect を追加
# またはそのまま実行：
electron --inspect=9229 .

その後、Chrome で chrome://inspect を開いてメインプロセスに接続します。

方法 2：VS Code

.vscode/launch.json に以下の設定を追加します：

{
  "type": "node",
  "request": "attach",
  "name": "Attach to Main Process",
  "port": 9229,
  "skipFiles": ["<node_internals>/**"]
}

レンダラープロセスのデバッグ

Ctrl+Shift+I（Windows/Linux）または Cmd+Option+I（macOS）を押して DevTools を開きます。

DevTools でサポートされている機能：

• React DevTools — 対応するブラウザ拡張機能をインストールすると自動的に読み込まれます
• Network — IPC 呼び出しを監視します（invoke リクエストとして表示されます）
• Performance — レンダリングパフォーマンスを分析します

ログ

Elftia はログ管理に Winston を使用しています。

環境変数	説明	デフォルト
LOG_LEVEL	ログレベル（debug / info / warn / error）	info

ログファイルの保存場所：

プラットフォーム	パス
Windows	%APPDATA%/elftia/logs/
macOS	~/Library/Application Support/elftia/logs/
Linux	~/.config/elftia/logs/

---

開発モードとプロダクションモードの違い

項目	開発モード	プロダクションモード
フロントエンド配信	Vite Dev Server（HMR）	静的ファイル（file://）
ソースマップ	有効	無効
ミニファイ	なし	Terser（console.log を削除）
コード分割	フル読み込み	ルートごとに React.lazy
CSP	緩和	厳格
DevTools	自動的に開く	デフォルトで非表示（開発者モードで有効化可）
データベース	開発用ユーザーデータディレクトリ	本番用ユーザーデータディレクトリ
ログレベル	debug	info

---

Worker スレッド

Elftia は IPC のブロッキングを防ぐため、メインプロセスで複数の Worker スレッドを生成します：

Worker	ファイル	担当処理
db.worker	workers/db/	SQLite の読み書き操作
fileSearch.worker	workers/fileSearch/	ファイル内容の検索（ripgrep）
fileWatcher.worker	workers/fileWatcher/	ファイルシステム変更の監視
mcp.worker	workers/mcp/	MCP サーバーとの通信
diagnostics.worker	workers/diagnostics/	システム診断情報の収集
project.worker	workers/project/	プロジェクトディレクトリのインデックス作成

開発モードでは Worker は ts-node を通じて TypeScript ソースを直接実行します。プロダクションモードでは tsup によってスタンドアロンの JS ファイルにコンパイルされます。

---

よくある問題

ネイティブモジュールのコンパイル失敗

# クリーンインストール
rm -rf node_modules
npm install

# またはネイティブモジュールのみを再コンパイル
npm run rebuild

ポートが使用中

Vite Dev Server はデフォルトでポート 5375 を使用します。使用中の場合：

# ポートを使用しているプロセスを特定
lsof -i :5375  # macOS/Linux
netstat -ano | findstr :5375  # Windows

データベースのロック

「database is locked」エラーが表示された場合は、Elftia のインスタンスが複数起動していないことを確認してください。開発時には diagnostics API を使用してデータベースの状態をエクスポートできます：

window.api.diagnostics.dump()