[Electron + Vite] 환경 설정과 트러블슈팅 가이드

1. 글의 목적

웹게임 끄투코리아의 게임 상태를 Discord RPC를 통해 디스코드에 표시하는 프로젝트를 진행하면서 작성한 개발기입니다.

크롬 익스텐션과 디스코드 간의 브리지 역할을 수행하는 일렉트론 앱을 개발하며 겪은 환경 설정 과정과 문제 해결 방법을 공유합니다.

📝 참고: 게임 상태를 추출하는 익스텐션 개발기는 별도 포스팅에서 다룰 예정입니다.

 

2. 사용한 기술스택 & 디렉토리 경로

주요 기술 스택

vite: ^7.1.0

react: ^19.1.1

electron: ^37.2.6

패키지 매니저: pnpm

그외 등등...

 

디렉터리 구조

모노레포 형식입니다.

rpc-app/
├── packages/
|    ├── electron/
│    │	 ├── main.ts
│    │   └── package.json
│    │
│    └── renderer/
│    	 ├── src/
│        |   ├── App.tsx
│        │   ├── App.css
│        │   ├── main.tsx
│        │   └── index.css
│        ├── package.json
│        └── vite.config.ts
├── package.json
└── pnpm-workspace.yaml

 

3. 기본 설정 및 설치

3-1. 모노레포 초기 설정

먼저 루트 디렉터리에 pnpm-workspace.yaml 파일을 생성합니다:

packages:
  - "packages/*"

루트에서 필요한 개발 도구들을 설치합니다:

 

pnpm add -D concurrently electron-builder wait-on

 

3-2. Renderer (React + Vite) 설정

# Vite + React + TypeScript 프로젝트 생성
pnpm create vite renderer --template react-ts

 

3-3. Electron 설정

# Electron 디렉토리 생성 및 초기화
mkdir electron
cd electron
pnpm init

 

electron/tsconfig.json 파일을 생성합니다:

{
    "compilerOptions": {
        "target": "ES2020",
        "module": "commonjs",
        "outDir": "dist",
        "strict": true,
        "esModuleInterop": true,
        "sourceMap": true,
        "skipLibCheck": true
    },
    "include": [
        "main.ts",
        "preload.ts"
    ]
}

필요한 패키지를 설치합니다:

pnpm add electron-is-dev
pnpm add -D cross-env electron

 

 

 

4. Electron 메인 프로세스 구현

 

electron/main.ts 파일을 생성합니다:

import electron from 'electron';
const { app, BrowserWindow } = electron;
import type { BrowserWindow as BrowserWindowType } from 'electron';
import path from 'path';
import isDev from 'electron-is-dev';

let mainWindow: BrowserWindowType | null = null;

function createWindow() {
  mainWindow = new BrowserWindow({
    width: 900,
    height: 680,
    webPreferences: {
      nodeIntegration: true,
      devTools: isDev,
    },
  });

  // 개발 환경에서는 개발 서버, 프로덕션에서는 빌드된 HTML 파일 로드
  mainWindow.loadURL(
    isDev
      ? "http://localhost:5173"
      : `file://${path.join(__dirname, "../renderer/dist/index.html")}`
  );

  if (isDev) {
    mainWindow.webContents.openDevTools({ mode: "detach" });
  }

  mainWindow.setResizable(true);
  mainWindow.on("closed", () => {
    mainWindow = null;
    app.quit();
  });
  mainWindow.focus();
}

app.on("ready", createWindow);

app.on("activate", () => {
  if (mainWindow === null) createWindow();
});

app.on("window-all-closed", () => {
  if (process.platform !== "darwin") app.quit();
});

 

5. 실행 스크립트 설정

루트 package.json에 스크립트를 추가합니다:

"scripts": {
    "dev": "concurrently \"pnpm --filter kkuko-extension-app-renderer dev\" \"wait-on http://localhost:5173 && pnpm --filter kkuko-extension-app-electron dev\"",
    "build": "pnpm --filter kkuko-extension-app-renderer build && pnpm --filter kkuko-extension-app-electron build && electron-builder",
    "build:win": "pnpm --filter kkuko-extension-app-renderer build && pnpm --filter kkuko-extension-app-electron build && electron-builder --win --x64"
  }

 

⚠️ 주의: pnpm --filter 뒤의 이름은 폴더명이 아닌 각 패키지의 package.json의 name 필드값입니다.

 

electron/package.json을 수정합니다

{
  ...,
  "main": "dist/main.js",
  "scripts": {
    "dev": "npm run build && electron .",
    "build": "tsc -b"
  },
  ...
}

 

 

 

6. 트러블슈팅: Electron 설치 오류

문제 상황

개발 서버를 실행하면 다음과 같은 오류가 발생했습니다:

Error: Electron failed to install correctly, please delete node_modules/electron and try installing again

해결 방법

이는 Electron이 완전히 설치되지 않아서 발생하는 문제입니다. 다음 명령어로 수동 설치를 진행합니다:

 

# Electron이 설치된 디렉토리에서 실행
node node_modules/electron/install.js

 

실행하면 Electron 바이너리 다운로드가 시작됩니다:

Downloading electron-v37.2.6-win32-x64.zip: [==========================================================================] 100% ETA: 0.0 seconds

 

실행 확인

문제가 해결된 후 다시 개발 서버를 실행하면:

pnpm run dev

정상적으로 Vite 개발 서버와 Electron 앱이 함께 실행됩니다.

 

7. 느낀점 & 마무리

장점

• 친숙한 개발 환경: React를 사용하여 기존 웹 개발 경험을 그대로 활용할 수 있어 UI 개발이 수월했습니다.
• 빠른 개발 속도: Vite의 빠른 HMR(Hot Module Replacement)로 개발 생산성이 높았습니다.
• 모노레포 구조: 프론트엔드와 일렉트론 코드를 체계적으로 관리할 수 있었습니다.

아쉬운 점

• Electron 설치 이슈: 초기 환경 설정에서 예상치 못한 설치 문제로 시간이 소요되었습니다.
• pnpm 워크스페이스: 초기 설정 시 패키지 필터링 부분에서 약간의 학습 곡선이 있었습니다.

 

8. 참고자료

Electron GitHub Issue #20731

https://lasbe.tistory.com/189