본문으로 건너뛰기

로컬 개발

이 가이드는 Elftia 로컬 개발 환경을 빠르게 설정하고 코딩을 시작하는 데 도움을 줍니다.

사전 요구 사항​

Node.js​

이 프로젝트는 Node.js v24가 필요합니다 (프로젝트 루트의 .nvmrc 참조). 버전 관리에는 nvm 또는 fnm 사용을 권장합니다:

nvm install
nvm use

네이티브 빌드 도구​

이 프로젝트는 better-sqlite3와 같은 네이티브 Node.js 모듈에 의존하며, C/C++ 컴파일 환경이 필요합니다:

플랫폼필요한 도구설치 방법
WindowsVisual Studio Build Tools 2022npm install -g windows-build-tools 또는 VS 공식 사이트에서 설치
macOSXcode Command Line Toolsxcode-select --install
Linuxbuild-essential, python3sudo 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 스크립트는 자동으로 다음을 수행합니다:

  • 현재 Electron 버전에 맞게 네이티브 모듈(better-sqlite3, node-pty 등)을 재컴파일
  • 플랫폼별 ripgrep 바이너리 다운로드
# 3. 환경 변수 파일 생성
cp .env.example .env

.env를 필요에 따라 편집하여 API 키 및 기타 설정을 입력합니다.

개발 모드 시작​

npm run dev

이 명령은 electron-vite dev를 시작하여 세 가지 타겟의 코드 변경을 동시에 감시합니다:

타겟디렉토리핫 리로드
Main Processpackages/desktop/app/main/메인 프로세스 재시작
Preload Scriptpackages/desktop/app/preload/메인 프로세스 재시작
Rendererpackages/renderer/src/Vite HMR (포트 5375)
팁

처음 시작 시 네이티브 모듈 오류가 발생하면, npm run rebuild를 실행하여 재컴파일해 보세요.

모든 개발 명령어​

명령어설명
npm run devElectron + Vite 개발 모드 시작 (main + preload + renderer)
npm run dev:webRenderer만 시작 (웹 모드, Electron 없음)
npm run dev:serverFastify 웹 서버 시작 (선택 사항)
npm run build모든 패키지 빌드 (renderer + desktop)
npm run build:renderer프론트엔드만 빌드 (Vite 프로덕션 모드)
npm run build:desktopElectron 메인 프로세스만 빌드 (tsup)
npm run build:official공식 릴리스 빌드 (서명 포함)
npm run build:steamSteam 버전 빌드
npm run lintESLint + TypeScript 타입 검사 실행
npm run lint:eslintESLint만 실행
npm run typecheckTypeScript 컴파일 검사만 실행
npm run testVitest 테스트 실행
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/

개발 vs 프로덕션 차이​

항목개발 모드프로덕션 모드
프론트엔드 서비스Vite Dev Server (HMR)정적 파일 (file://)
소스 맵활성화비활성화
압축없음Terser (console.log 제거)
코드 분할전체 로드라우트별 React.lazy
CSP완화엄격
DevTools자동으로 열림기본적으로 숨김 (개발자 모드에서 활성화 가능)
데이터베이스개발 사용자 데이터 디렉토리프로덕션 사용자 데이터 디렉토리
로그 레벨debuginfo

Worker 스레드​

Elftia는 IPC 차단을 방지하기 위해 메인 프로세스에서 여러 Worker 스레드를 생성합니다:

Worker파일역할
db.workerworkers/db/SQLite 읽기/쓰기 작업
fileSearch.workerworkers/fileSearch/파일 내용 검색 (ripgrep)
fileWatcher.workerworkers/fileWatcher/파일 시스템 변경 모니터링
mcp.workerworkers/mcp/MCP 서버 통신
diagnostics.workerworkers/diagnostics/시스템 진단 수집
project.workerworkers/project/프로젝트 디렉토리 인덱싱

개발 모드에서 Worker는 ts-node를 통해 TypeScript 소스를 직접 실행하고, 프로덕션 모드에서 Worker는 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 인스턴스가 실행되지 않는지 확인합니다. 개발 중에는 진단 API를 사용하여 데이터베이스 상태를 내보낼 수 있습니다:

window.api.diagnostics.dump()