[Electron 데스크톱 앱 개발] #5: Electron 앱 패키징하기 (Windows 실행 파일 만들기)

✨ 목표

지금까지는 npm start 명령어를 통해 개발 환경에서만 앱을 실행했습니다.

이번에는 지금까지 만든 Electron 앱을 Windows에서 일반 프로그램처럼 실행할 수 있는 형태로 패키징해보겠습니다.

• Electron Forge 설치하기
• 기존 Electron 프로젝트를 Forge 프로젝트로 변환하기
• Electron 앱 패키징하기
• Windows용 설치파일 만들기
• 생성된 설치파일로 실제 프로그램 설치 및 실행하기

---

✔️ 1. Electron 앱 패키징이란?

지금까지는 프로젝트 폴더에서

npm start

명령어를 실행해야 Electron 앱을 사용할 수 있었습니다.

하지만 실제로 다른 사람에게 프로그램을 전달하려면 개발 환경 없이도 실행할 수 있는 형태로 만들어야 합니다.

Electron에서는 앱의 코드와 Electron 실행 환경을 함께 패키징하여 배포 가능한 프로그램을 만들 수 있습니다. Electron 공식 문서에서도 이러한 패키징과 배포 과정을 별도의 단계로 안내하고 있습니다.

이번 글에서는 Electron Forge를 사용해 Windows용 실행 파일을 만들어보겠습니다.

---

✔️ 2. Electron Forge 설치하기

먼저 현재 Electron 프로젝트에 Electron Forge를 설치합니다.

VSCode 프로젝트 폴더에서 터미널을 열고 다음 명령어를 실행합니다.

npm install --save-dev @electron-forge/cli

설치가 완료되면 현재 프로젝트를 Electron Forge에서 사용할 수 있도록 변환합니다.

npx electron-forge import

import 명령어는 기존에 만들어둔 Electron 프로젝트를 Forge 프로젝트 형태로 변환해줍니다.

기존 프로젝트를 처음부터 다시 만들 필요 없이, 지금까지 작성한 Electron 앱을 그대로 패키징 과정에 사용할 수 있다는 점이 편리합니다.

npx electron-forge import가 완료되면 프로젝트에 forge.config.js 파일이 생성됩니다.

 

기존에는 다음과 같이 Electron을 직접 실행했습니다.

"scripts": {
  "start": "electron ."
}

Forge를 적용하면 다음과 같은 명령어가 추가됩니다.

"scripts": {
  "start": "electron-forge start",
  "package": "electron-forge package",
  "make": "electron-forge make"
}

---

✔️ 3. 프로젝트 구조 확인하기

Electron Forge를 적용한 후에는 프로젝트에 새로운 설정 파일과 패키지가 추가됩니다.

electron-app
├─ node_modules
├─ .gitignore
├─ index.html
├─ main.js
├─ package-lock.json
├─ package.json
├─ README.md
├─ script.js
├─ style.css
└─ forge.config.js

forge.config.js는 Electron Forge에서 앱을 패키징하고 배포할 때 필요한 설정을 관리하는 파일입니다.

---

✔️ 4. 개발 환경에서 다시 실행해보기

Forge를 적용했다고 해서 기존 앱이 바로 변경되는 것은 아닙니다.

먼저 기존 앱이 정상적으로 실행되는지 확인해보겠습니다.

npm start

기존에 만들었던 랜덤 룰렛이 정상적으로 실행되는지 확인합니다.

참가자를 추가하고 룰렛을 실행해 기존 기능에도 문제가 없는지 확인합니다.

---

✔️ 5. Electron 앱 패키징하기

이제 실제로 Electron 앱을 패키징해보겠습니다.

다음 명령어를 실행합니다.

npm run package

package 명령은 Electron 앱의 코드를 Electron 실행 환경과 함께 묶어 패키징된 앱을 만드는 과정입니다.

Electron Forge에서는 package 단계에서 패키징된 앱을 생성하고, 이후 make를 통해 실제 배포용 파일을 만들 수 있습니다.

명령어가 정상적으로 실행되면 프로젝트에 out 폴더가 생성됩니다.

electron-app
├─ ...
└─ out
       └─ 랜덤 룰렛 앱

이 단계에서는 아직 일반적인 의미의 설치파일을 만든 것은 아닙니다.

Electron 앱과 실행에 필요한 환경을 하나로 묶어 배포할 수 있는 형태로 만드는 과정이라고 이해하면 됩니다.

즉,

개발 프로젝트
      ↓
npm run package
      ↓
패키징된 Electron 앱

의 과정입니다.

---

✔️ 6. Windows 실행 파일 만들기

이제 패키징된 앱을 실제 Windows에서 사용할 수 있는 설치 파일을 만들어보겠습니다.

터미널에서 다음 명령어를 실행합니다.

npm run make

make 명령은 먼저 앱을 패키징한 다음, 설정된 Maker를 이용해 운영체제에 맞는 배포 파일을 생성합니다.

 

❗️Windows 설치파일 생성 중 오류 해결

`npm run make`를 실행했는데 다음과 같은 오류가 발생했습니다.
> Authors is required.

Electron Forge에서 Windows용 Squirrel 설치파일을 생성하는 과정에서
author 정보가 필요했기 때문에 발생한 오류였습니다.

package.json의 author항목이 없거나 비어 있다면 작성자 정보를 입력합니다.
저장한 후 다시 "npm run make"을 실행합니다.

👉 [Electron Forge] "Authors is required" 오류 해결하기

 

실행이 완료되면 out 폴더 안에 배포용 파일들이 생성됩니다.

일반적으로 다음과 같은 구조를 확인할 수 있습니다.

out
├─ 랜덤룰렛-win32-x64
│    ├─ 랜덤룰렛.exe
│    └─ ...
└─ make
      └─ squirrel.windows
            └─ x64
                  ├─ 랜덤룰렛-1.0.0 Setup.exe
                  └─ ...

여기에서 생성된 Setup.exe 파일이 Windows에서 프로그램을 설치할 때 사용하는 설치파일입니다.

따라서 지금까지는

npm start

를 실행해야만 사용할 수 있었던 앱을,

Setup.exe

를 통해 Windows에 설치해서 사용할 수 있는 형태로 만들게 된 것입니다.

💡 참고
랜덤룰렛.exe = 패키징된 앱의 실행파일 (폴더 전체를 다른 PC로 전달해 실행 가능)
Setup.exe = Windows에 프로그램을 설치하기 위한 설치파일

---

✔️ 7. 설치파일로 Windows 프로그램 설치

생성된 Setup.exe 파일을 실행해봅니다.

설치 프로그램을 실행하면 Windows에 랜덤 룰렛 앱이 설치됩니다.

정상적으로 실행된다면 지금까지 개발했던 랜덤 룰렛이 별도의 개발 명령어 없이 Windows 프로그램으로 실행됩니다.

이제 더 이상 VS Code에서 프로젝트 폴더를 열고 npm start를 입력하지 않아도 프로그램을 실행할 수 있습니다.

즉, 기존에는

개발 단계
VS Code → 터미널 → npm start

과정이 필요했다면,

패키징 후에는

배포 단계
Windows → 설치된 프로그램 실행

처럼 직접 실행할 수 있습니다.

이렇게 해서 지금까지 개발한 Electron 앱을 Windows에서 실행할 수 있는 형태로 만들어봤습니다.

---

✔️ 8. 실행해보기

설치

💡 참고
RELEASES와 .nupkg는 Squirrel.Windows의 설치/업데이트 과정에서 사용되는 배포 관련 파일이다.

Setup.exe
→ 사용자가 실행하는 설치파일

.nupkg
→ 앱 패키지

RELEASES
→ 버전 및 패키지 정보를 관리하는 파일