Локальная разработка

Это руководство поможет быстро настроить локальное окружение разработки Elftia и начать писать код.

Предварительные требования

Node.js

Проекту требуется Node.js v24 (см. .nvmrc в корне проекта). Рекомендуем использовать nvm или fnm для управления версиями:

nvm install
nvm use

Нативные инструменты сборки

Проект зависит от нативных модулей Node.js, таких как better-sqlite3, которым требуется окружение компиляции 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. Clone the repository
git clone <repo-url> elftia
cd elftia

# 2. Install dependencies
npm install

Скрипт postinstall, запускаемый командой npm install, автоматически:

• Перекомпилирует нативные модули (better-sqlite3, node-pty и т. д.) под текущую версию Electron
• Скачивает бинарный файл ripgrep для вашей платформы

# 3. Create the environment variable file
cp .env.example .env

При необходимости отредактируйте .env, чтобы указать API-ключи и другую конфигурацию.

---

Запуск режима разработки

npm run dev

Эта команда запускает electron-vite dev, одновременно отслеживая изменения кода в трех целях:

Цель	Каталог	Горячая перезагрузка
Основной процесс	packages/desktop/app/main/	Перезапускает основной процесс
Скрипт preload	packages/desktop/app/preload/	Перезапускает основной процесс
Renderer	packages/renderer/src/	Vite HMR (порт 5375)

подсказка

Если при первом запуске возникают ошибки нативных модулей, попробуйте выполнить npm run rebuild, чтобы перекомпилировать их.

---

Все команды разработки

Команда	Описание
npm run dev	Запустить режим разработки Electron + Vite (main + preload + renderer)
npm run dev:web	Запустить только Renderer (веб-режим, без Electron)
npm run dev:server	Запустить веб-сервер Fastify (опционально)
npm run build	Собрать все пакеты (renderer + desktop)
npm run build:renderer	Собрать только фронтенд (production-режим 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	Проанализировать состав bundle (статистика chunk)

---

Отладка

Отладка основного процесса

Способ 1: флаг --inspect

# Add --inspect to the dev script in package.json
# Or run directly:
electron --inspect=9229 .

Затем откройте chrome://inspect в Chrome и подключитесь к основному процессу.

Способ 2: VS Code

Добавьте следующую конфигурацию в .vscode/launch.json:

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

Отладка процесса Renderer

Нажмите 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/

---

Различия между разработкой и production

Аспект	Режим разработки	Production-режим
Раздача фронтенда	Vite Dev Server (HMR)	Статические файлы (file://)
Source maps	Включены	Отключены
Минификация	Нет	Terser (удаляет console.log)
Разделение кода	Полная загрузка	React.lazy по маршрутам
CSP	Ослабленная	Строгая
DevTools	Открывается автоматически	По умолчанию скрыт (можно включить в режиме разработчика)
База данных	Каталог пользовательских данных для разработки	Каталог пользовательских данных для production
Уровень логирования	debug	info

---

Worker Threads

Elftia запускает несколько Worker threads в основном процессе, чтобы не блокировать IPC:

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 запускают исходный TypeScript напрямую через ts-node; в production-режиме worker компилируются tsup в самостоятельные JS-файлы.

---

Распространенные проблемы

Ошибка компиляции нативного модуля

# Clean and reinstall
rm -rf node_modules
npm install

# Or recompile native modules only
npm run rebuild

Порт уже используется

Vite Dev Server по умолчанию использует порт 5375. Если он занят:

# Find the process using the port
lsof -i :5375  # macOS/Linux
netstat -ano | findstr :5375  # Windows

База данных заблокирована

Если вы видите ошибку "database is locked", убедитесь, что запущен не более чем один экземпляр Elftia. В режиме разработки можно экспортировать состояние базы данных через diagnostics API:

window.api.diagnostics.dump()