[Electron] React + Electron 배포하기(build)

https://deahan.tistory.com/485

[Electron] Electron + React(vite) 프로젝트 한방에 띄우기

나는 이 블로그 글을 이어서 작성한다.

 

어찌됐든 데스크 탑 앱을 React + vite + typescript로 멋지게 개발했으면 남들에게 자랑을 해야한다.

 

현재 상태는 일렉트론이 http://localhost:5173/라는 Vite 개발 서버를 웹 브라우저처럼 띄워서 보여주고 있는 상태이다.

이것을 다른 사람에게 자랑하려면 .exe 파일로 만들어 넘겨야한다, 이를 수행하기 위해서는

1) React 코드를 정적 파일(HTML, JS, CSS)로 변환(Build)하고,
2) 그 파일들을 일렉트론 실행 파일 안에 하나로 포장(Packaging) 하는 과정이 필요합니다.

이를 가장 쉽고 강력하게 도와주는 electron-builder를 사용하여 배포용 .exe 파일을 만드는 방법을 단계별로 설명해보겠다.

 

1. 패키징 도구설치 

터미널을 열고 일렉트론 앱을 .exe로 만들어 줄 electron-builder를 개발용 의존성으로 추가한다.

npm install electron-builder --save-dev

2. vite.config.ts 경로 수정 (매우 중요)

일렉트론은 웹 서버가 아니라 컴퓨터의 로컬 파일 시스템(file://) 에서 HTML 파일을 직접 연다.

Vite는 기본적으로 절대 경로(/assets/...)로 빌드하기 때문에, 이를 상대 경로(./assets/...)로 바꿔주지 않으면 빈 하얀 화면만 나오게 된다.

//vite.config.ts

import { defineConfig } from 'vite'

import react from '@vitejs/plugin-react'

// https://vite.dev/config/

export default defineConfig({

  plugins: [react()],

  base: './'

})

 

3. main.js 배포 모드 분기 처리

현재 main.js는 무조건 localhost:5173을 바라보게 되어 있다. 이를 "개발 모드일 때는 localhost를 보고, 패키징(빌드)된 상태일 때는 Vite가 빌드한 HTML 파일을 보도록" 수정해야 한다.

src/main.js 파일을 다음과 같이 수정한다.

//main.js

const { app, BrowserWindow } = require('electron')

const path = require('path')

function createWindow () {

  const win = new BrowserWindow({

    width: 800,

    height: 600,

    webPreferences: {

      nodeIntegration: true,

      contextIsolation : false

    }

  })

  // app.isPackaged를 통해 .exe로 빌드된 상태인지 확인

  if (app.isPackaged) {

    // 배포 환경: Vite가 빌드한 dist 폴더 안의 index.html을 로드

    // main.js가 src/ 폴더 안에 있으므로, 상위 폴더(../)의 dist/로 접근

    win.loadFile(path.join(__dirname, '../dist/index.html'))

  } else {

    // 개발 환경: 기존처럼 Vite 개발 서버를 로드

    win.loadURL("http://localhost:5173/")

  }

}

app.whenReady().then(() => {

  createWindow()

})

app.on('window-all-closed', function () {

  app.quit()

})

 

4. package.json 빌드 설정 추가

이제 electron-builder에게 어떤 파일들을 묶어서 .exe로 만들지 설정을 적어주어야 한다. package.json 파일을 열어 다음 내용들을 추가해 준다.

 

//package.json

{

  "name": "electron",

  "private": true,

  "version": "1.0.0",

  "main": "src/main.js",

  "scripts": {

    "start": "concurrently -k \"npm run dev\" \"npm run electron\"",

    "dev": "vite",

    "build": "tsc -b && vite build",

    "lint": "eslint .",

    "preview": "vite preview",

    "electron": "wait-on http://localhost:5173 && electron .",

    "dist": "npm run build && electron-builder --win"

  },

  "build": {

    "appId": "com.myname.electronapp",

    "productName": "프로젝트 이름",

    "directories": {

      "output": "release"

    },

    "files": [

      "dist/**/*",

      "src/main.js"

    ],

    "win": {

      "target": "nsis"

    }

  },

  "dependencies": {

    "react": "^19.2.4",

    "react-dom": "^19.2.4"

  },

  "devDependencies": {

    "@eslint/js": "^9.39.4",

    "@types/node": "^24.12.2",

    "@types/react": "^19.2.14",

    "@types/react-dom": "^19.2.3",

    "@vitejs/plugin-react": "^6.0.1",

    "concurrently": "^9.2.1",

    "electron": "^41.1.1",

    "electron-builder": "^26.8.1",

    "eslint": "^9.39.4",

    "eslint-plugin-react-hooks": "^7.0.1",

    "eslint-plugin-react-refresh": "^0.5.2",

    "globals": "^17.4.0",

    "typescript": "~6.0.2",

    "typescript-eslint": "^8.58.0",

    "vite": "^8.0.4",

    "wait-on": "^9.0.4"

  }

}

 

 

 

 

• "dist" 스크립트는 Vite로 React를 먼저 빌드(npm run build)한 후, 일렉트론 앱을 윈도우용으로 패키징(electron-builder --win)한다
• "files" 배열은 .exe 파일 안에 실제로 포함될 파일들만 쏙 골라내는 역할 (Vite가 빌드한 dist 폴더와 일렉트론 실행 파일인 src/main.js만 포함시킨다.)

5. Build 실행!

모든 준비가 끝났다. 터미널에 다음 명령어를 입력해보자

npm run dist

 

 

시간이 조금 지나고 처리가 완료되면, 프로젝트 폴더 안에 release 라는 새로운 폴더가 생성된다. 그 폴더 안에 들어가 보면 MyFirstElectronApp Setup 1.0.0.exe 와 같은 멋진 설치 파일이 만들어져 있을 것이다.

 

새로 만들어진 release 폴더 안에 들어가보면 아래처럼 .exe어플이 하나 있다 실행한다.

 

 

자랑할 파일을 더블클릭!!

 

게이지가 차오르며 설치가 완료되면 아래 바탕화면의 아이콘과 함께 실행된다.

아이콘을 실행하면 어플이 실행된다.

이제 이파일로 내가만든 멋진 프로젝트를 사람들에게 자랑하도록 하자!