Electron + TypeScript

Electron이라는 프레임워크를 사용하면 HTML, CSS, JavaScript를 사용하여 웹 개발하듯이 PC용 응용 프로그램을 만들 수 있습니다. TypeScript는 JavaScript에 타입 문법이 추가된 언어입니다. 오늘은 Electron 프레임워크와 TypeScript를 결합하여 앱을 만들어 보겠습니다.

1. Electron+TypeScript 개발 환경 구축

1.1. Node.js가 필요합니다. Node.js가 설치되어 있지 않다면 먼저 설치합니다.
Windows PC에 Node.js 설치, npm 명령어

1.2. Electron 개발할 폴더에서 터미널을 열고 npm init -y 명령을 실행하여 초기화합니다. 그러면 package.json이 생성됩니다.

개발 환경 설치
1.3. npm install -D electron typescript copyfiles 명령을 실행합니다.
참고로 copyfiles는 개발 운영체제마다 복사 명령어가 다른 것을 통합해 주는 라이브러리입니다.

Version 5.8.2
1.4. npx tsc -v 명령어를 실행하여 package.json에 나와 있는 typescript 버전이 터미널에도 잘 표시되는지 확인합니다.

npx tsc --init
1.5. npx tsc –init 명령어를 실행합니다. 그러면 tsconfig.json 파일이 생성됩니다.
1.6. src 폴더를 만듭니다. 예제 폴더 구조는 아래와 같습니다.

📁build: 컴파일 후 빌드 결과물이 저장될 폴더
📁node_modules
📁src: 컴파일 전 소스코드들을 저장하는 폴더
- image
  - icon.png: 프로그램 아이콘
- index.html: 앱 실행 첫 화면
- main.ts: 앱 구동과 관련된 TypeScript 코드
- 기타 웹 개발에 사용한 파일들(css, ts, js, 이미지 등)
package-lock.json
package.json
tsconfig.json

2. tsconfig.json

tsconfig.json

{
  "compilerOptions": {
    /* Language and Environment */
    //...(중략)

    /* Modules */
    "module": "commonjs",                                /* Specify what module code is generated. */
    "rootDir": "./src",                                  /* Specify the root folder within your source files. */
    //...(중략)

    /* Emit */
    "outDir": "./build",                                   /* Specify an output folder for all emitted files. */

    /* Interop Constraints */
    //...(중략)

    /* Type Checking */
    //...(중략)

    /* Completeness */
    //...(중략)
  }
}

[스크린샷 30행, 코드블록 8행]
“rootDir”: “./src“,
src 폴더 안의 파일들만 컴파일합니다.

[스크린샷 62행, 코드블록 12행]
“outDir”: “./build“,
컴파일 결과물들을 build 폴더 안에 저장합니다.

3. package.json

{
  "name": "practice2",
  "version": "1.0.0",
  "main": "build/main.js",
  "scripts": {
    "compile": "tsc && copyfiles -u 1 src/**/* -e src/**/*.ts -e src/**/*.js build",
    "start": "npm run compile && electron ."
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "description": "",
  "devDependencies": {
    "copyfiles": "^2.4.1",
    "electron": "^35.0.2",
    "typescript": "^5.8.2"
  }
}

4행(main)과 5~7행(scripts)만 수정하면 됩니다.
(그 외 name, version, keywords, author, license, description은 임의로 설정하시고, devDependencies는 건드리지 마세요.)

[Line 4 main]
“main”: “build/main.js”,

[Line 6 compile]

npm run compile 명령어를 사용하면 실행할 것을 설정하는 부분입니다.
먼저 TypeScript 컴파일을 합니다. 그러나 그럴 경우 build 폴더 안에 컴파일된 JavaScript 파일만 있고, HTML이나 CSS 등은 여전히 src 폴더에 있기 때문에 src 폴더 안의 파일들을 build 폴더로 복사합니다. 이때 TypeScript 코드와 JavaScript 코드는 제외하며, 최상위 폴더(src)는 벗깁니다.

[Line 7 start]
“start”: “npm run compile && electron .”
npm run start 명령어를 사용하면 npm run compile과 electron .이 순서대로 실행됩니다.

4. src/main.ts

src 폴더 안에 main.ts를 생성합니다.
main.ts는 기본적인 Electron main.js 코드와 동일하게 작성하셔도 되는데, TypeScript를 사용할 때는 보통 require 대신 import를 사용하더라고요. 아래 코드와 같이 작성하시면 되겠습니다.

import { app, BrowserWindow } from 'electron'
import path from 'node:path'

const createWindow = () => {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    icon: path.join(__dirname, '/image/icon.png')
  })

  win.loadFile('src/index.html')
}

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

  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) {
      createWindow()
    }
  })
})

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

[Line 2 path]
import path from ‘node:path’
Node.js의 path 모듈을 불러옵니다.

[Line 4~12 createWindow 함수 정의]
앱 실행 시 창을 만드는 것에 대한 내용입니다.

[Line 6 width]
width: 800
창 가로 길이를 입력합니다.

[Line 7 height]
height: 600
창 세로 길이를 입력합니다.

[Line 8 icon]
icon: path.join(__dirname, ‘/image/icon.png’)
path.join method는 플랫폼(Windows/Linux/macOS)별로 구분자를 사용하여 경로를 정규화 해 줍니다. path.join의 2번째 인자에 아이콘 파일 경로를 넣습니다.

[Line 11]
win.loadFile(‘src/index.html’)
앱을 실행하면 src/index.html을 띄웁니다.

[Line 13~15]
앱을 실행하면 createWindow 함수를 호출하여 창을 생성합니다.

[Line 17~22(macOS를 위한 코드)]
macOS는 창이 모두 닫혀도 앱이 종료되지 않습니다. 따라서 창이 1개도 없을 때 createWindow 함수를 호출하는 코드가 필요합니다.

[Line 24~28(Windows와 Linux를 위한 코드)]
창이 모두 닫히면 앱을 종료합니다.

5. 웹 소스코드 작성

이제 웹개발하듯이 소스코드를 작성합니다. 다만, 이때 첫 화면은 index.html로 합니다.
이 글에서는 https://github.com/sooseongcom/test.git 예제를 사용하겠습니다. 제 예제를 그대로 사용하시려면 소스코드들을 내려받아 src 폴더 안에 넣으시면 됩니다.

electron_practice
제 예제를 그대로 사용할 경우 프로젝트 폴더 안에 이러한 파일들이 있게 됩니다.

6. HTML 코드에 CSP 메타태그 추가

모든 HTML 코드의 head 태그 그룹에 아래 코드를 추가합니다.(5번 문단의 예제 코드에는 CSP 메타태그가 미적용 되어 있으므로 추가해야 함.)

<!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'"/>
<meta http-equiv="X-Content-Security-Policy" content="default-src 'self'; script-src 'self'"/>

이 메타태그를 추가하면 inline JavaScript가 작동하지 않으며 같은 출처에서만 리소스(ex. 스크립트)를 로드할 수 있게 됩니다.
참고) inline JavaScript는 XSS 취약점 문제가 있음.

CSP 메타태그를 추가하지 않으면 개발자 도구에서 Electron Security Warning (Insecure Content-Security-Policy) 경고가 뜹니다.

7. 디버깅(npm start)

서버에 오신 것을 환영합니다
이제 npm start 명령을 실행하면 웹 소스코드대로 앱이 구현되어 실행됩니다.

8. 글 마무리

제 글을 읽어 주셔서 감사합니다. 다음에 만나요!

9. 참고 자료

1) 개발하는 사람. 2022. “[Electron] 01. Electron + Typescript 시작하기”, 데브사피엔스. (2025. 03. 19. 방문). https://devsapiens.tistory.com/entry/Electron-01-시작하기
2) 둥굴프. 2023. “[TS] Typescript 컴파일러”, 둥글게 굴러가는 프로그램. (2025. 03. 19. 방문). https://roll-over-program.tistory.com/75
3) ghiscoding. 2018 외 2명. “npm copyfiles without container folder”, stackoverflow. (2025. 03. 19. 방문). https://stackoverflow.com/questions/49054610/npm-copyfiles-without-container-folder

필자(수성컴)의 노트북은 갤럭시 북 Flex2입니다.(Windows 11)

목차