Electron과 React 설정하기

Electron에서 React를 설정하려면 먼저 Vite React 프로젝트를 만들고 electron과 electron-builder를 devDependencies로 추가합니다. 프로젝트에는 두 개의 진입점이 생깁니다. 하나는 렌더러용 Vite 앱이고, 다른 하나는 Electron 메인 프로세스용 main.js 파일입니다.

main.js는 Electron의 진입점입니다. 원하는 창 크기와 보안 설정으로 BrowserWindow를 만든 다음 React 앱을 로드합니다. 개발 중에는 localhost:5173을 가리키고, 배포 환경에서는 빌드된 파일 경로를 가리킵니다.

electron-vite는 Vite와 Electron을 통합하는 올인원 빌드 도구로, 복잡한 다중 프로세스 빌드 구성을 자동으로 처리합니다. 메인, 프리로드, 렌더러에 사용할 별도의 Vite 구성을 제공하며 개발 및 배포용 빌드를 모두 크게 간소화합니다.

Electron용 Vite를 구성할 때는 자동 검색에 의존하지 말고 브라우저 대상을 명시적으로 설정해야 합니다. 렌더러가 Electron에 포함된 특정 Chromium 버전에서 실행되기 때문입니다. electron-vite는 이 작업을 자동으로 처리하지만, 수동으로 구성할 때는 빌드 대상에 Chrome 버전을 지정해야 합니다.

electron-vite dev를 실행하면 렌더러용 Vite 개발 서버와 Electron 메인 프로세스가 동시에 시작됩니다. Vite 개발 서버는 HMR(핫 모듈 교체)을 제공하므로 React 컴포넌트의 변경 사항이 전체 재시작 없이 Electron 창에 즉시 반영됩니다.

HMR은 브라우저에서와 마찬가지로 Electron 렌더러에서도 작동하여 상태를 유지하면서 수정된 컴포넌트를 즉시 다시 렌더링합니다. main.js나 프리로드 스크립트는 Vite HMR 경계 밖에서 실행되므로 해당 파일을 변경하면 Electron을 완전히 다시 시작해야 합니다.

Electron + React + TypeScript 프로젝트에는 메인(Node.js/CommonJS 대상), 프리로드(Node 전역 기능을 포함한 브라우저와 유사한 환경 대상), 렌더러(표준 브라우저 TypeScript 대상)에 각각 별도의 tsconfig 파일이 필요합니다. electron-vite는 이러한 구성을 자동으로 생성합니다.

프리로드 스크립트는 contextBridge.exposeInMainWorld를 사용하여 사용자 지정 API를 렌더러에 노출합니다. 일반적으로 "api"와 같은 네임스페이스를 노출하고, 그 안에 ipcRenderer.invoke 호출을 감싼 함수를 제공하여 React 컴포넌트가 메인 프로세스 작업을 깔끔한 비동기 인터페이스로 사용할 수 있게 합니다.

어떤 React 컴포넌트에서든 window.api.myFunction()을 호출하여 프리로드에서 노출한 API를 사용할 수 있습니다. TypeScript 사용자는 일반적으로 전역 선언(window: Window & { api: MyAPI })을 추가하여 노출된 인터페이스에 대한 타입 검사와 자동 완성을 지원받습니다.

electron-vite build는 세 대상(메인, 프리로드, 렌더러)을 모두 컴파일하여 dist/ 폴더에 저장합니다. 그런 다음 electron-builder가 이를 플랫폼별 설치 프로그램으로 패키징합니다. 배포 환경의 main.js는 개발 서버 URL이 아니라 번들로 묶인 파일 경로에서 렌더러를 로드합니다.

가장 자주 발생하는 설정 실수는 nodeIntegration:false와 contextIsolation:true를 잊는 것(보안 취약점 발생), main.js에서 잘못된 URL을 로드하는 것(개발 환경과 배포 환경을 혼동하는 것), 렌더러에서 Electron 모듈을 직접 가져오는 것(충돌 발생)입니다. electron-vite의 기본 설정은 이러한 문제 대부분을 방지합니다.

electron-vite dev를 실행하면 어떤 작업이 수행되나요?

Electron에서 React를 설정하는 과정은 electron-vite를 통해 간소화되며, electron-vite가 다중 프로세스 빌드의 복잡성을 처리합니다. 개발 작업 흐름에서는 완전한 HMR 지원을 제공하고, contextBridge는 렌더러 API 표면을 보호하며, 별도의 TypeScript 구성은 각 프로세스에 올바른 타입 환경을 제공합니다. 배포용 빌드에는 플랫폼별 패키징을 위해 electron-builder를 사용합니다.