Electron

lastmod 2026-06-26created 2017-01-3043 edits

If you can build a website, you can build a desktop app. Electron is a framework for creating native applications with web technologies like JavaScript, HTML, and CSS. It takes care of the hard parts so you can focus on the core of your application.

Category

• Electron:QuickStart
• Electron:Python - A chronicle of fumbling attempts to integrate Python with Electron
• Electron Fiddle - Electron, quickly and easily

Libraries

• electron-builder
• electron-vue (vue) - Integrates vue into electron from the start.
• Vue CLI Plugin Electron Builder - Starts an already-built vue project as a Background Process, then uses electron only as a web-view.
• Nextron (Next.js + Electron)

Projects

• Github - surfbird: A Microblogging client built on Electron and Vue
• fbs - A lightweight alternative to Electron

Update server

• Updating Applications | Electron

Depending on your needs, you can choose from one of these:

• Hazel - An update server for private or open-source apps that can be deployed for free on Vercel. It pulls from GitHub releases and leverages the power of GitHub's CDN.
• Nuts - Also uses GitHub releases, but caches app updates on disk and supports private repositories.
• electron-release-server - Provides a dashboard for handling releases, and releases don't need to originate on GitHub.
• Nucleus - A complete update server for Electron apps maintained by Atlassian. Supports multiple applications and channels. Uses a static file store to minimize server costs.

Quick start

• Getting started - Electron

const electron = require('electron')
// 애플리케이션 생명주기를 조작 하는 모듈.
const {app} = electron
// 네이티브 브라우저 창을 만드는 모듈.
const {BrowserWindow} = electron

// 윈도우 객체를 전역에 유지합니다. 만약 이렇게 하지 않으면
// 자바스크립트 GC가 일어날 때 창이 멋대로 닫혀버립니다.
let win

function createWindow () {
  // 새로운 브라우저 창을 생성합니다.
  win = new BrowserWindow({width: 800, height: 600})

  // 그리고 현재 디렉터리의 index.html을 로드합니다.
  win.loadURL(`file://${__dirname}/out/index.html`)

  // 개발자 도구를 엽니다.
  win.webContents.openDevTools()

  // 창이 닫히면 호출됩니다.
  win.on('closed', () => {
    // 윈도우 객체의 참조를 삭제합니다. 보통 멀티 윈도우 지원을 위해
    // 윈도우 객체를 배열에 저장하는 경우가 있는데 이 경우
    // 해당하는 모든 윈도우 객체의 참조를 삭제해 주어야 합니다.
    win = null
  })
}

// 이 메서드는 Electron의 초기화가 끝나면 실행되며 브라우저
// 윈도우를 생성할 수 있습니다. 몇몇 API는 이 이벤트 이후에만
// 사용할 수 있습니다.
app.on('ready', createWindow)

// 모든 창이 닫히면 애플리케이션 종료.
app.on('window-all-closed', () => {
  // macOS의 대부분의 애플리케이션은 유저가 Cmd + Q 커맨드로 확실하게
  // 종료하기 전까지 메뉴바에 남아 계속 실행됩니다.
  if (process.platform !== 'darwin') {
    app.quit()
  }
})

app.on('activate', () => {
  // macOS에선 보통 독 아이콘이 클릭되고 나서도
  // 열린 윈도우가 없으면, 새로운 윈도우를 다시 만듭니다.
  if (win === null) {
    createWindow()
  }
})

// 이 파일엔 제작할 애플리케이션에 특화된 메인 프로세스 코드를
// 포함할 수 있습니다. 또한 파일을 분리하여 require하는 방법으로
// 코드를 작성할 수도 있습니다.

Building without the FUSE dependency (electron-builder)

To avoid FUSE/sandbox issues in distribution, build deb and tar.gz targets alongside AppImage. deb sets chrome-sandbox permissions automatically on installation.

Edit the electron-builder.yml file:

linux:
  target:
    - AppImage
    - deb
    - tar.gz
  category: Utility

Then run the following:

npm run package
sudo dpkg -i dist/App_0.1.0_amd64.deb
# 압축 해제형 산출물 (FUSE 불필요)
npm run package:dir   # → dist/linux-unpacked/<app>

Building for the Windows target

You can build the win target (nsis installer) on Linux. electron-builder automatically downloads the Electron binary for Windows and packages it.

npx electron-builder --win

Or make the package script win-only:

npm run build && ./npm run protect && ./npx electron-builder --win

=== NSIS installer = Wine required === win.target: nsis has to run Windows tools internally, so Wine must be installed on Linux. The cleanest way is to use the official electron-builder Docker image.

docker run --rm -ti \
  -v ${PWD}:/project \
  -v ~/.cache/electron:/root/.cache/electron \
  -v ~/.cache/electron-builder:/root/.cache/electron-builder \
  electronuserland/builder:wine \
  /bin/bash -c "npm ci && npx electron-builder --win"

User permission approach

#!/usr/bin/env bash

# Windows(NSIS) 데모 빌드. electronuserland/builder:wine 이미지를 사용한다.
#
# 컨테이너는 root 로 실행한다: protect 단계가 ELECTRON_RUN_AS_NODE 로 Electron 을 띄워
# 바이트코드(.jsc)를 컴파일하는데, 이 이미지에는 Electron 바이너리가 동적 링크하는 GUI
# 공유 라이브러리(libatk 등)가 없어 apt-get 으로 설치해야 하기 때문이다(설치=root 필요).
#
# 대신 빌드가 끝나면(실패해도 trap 으로) 생성물·캐시 소유권을 현재 사용자/그룹으로
# 되돌려, 호스트에 root 소유 파일이 남지 않게 한다.

HOST_UID=$(id -u)
HOST_GID=$(id -g)

docker run --rm -ti \
    -v "${PWD}:/project" \
    -v ~/.cache/electron:/root/.cache/electron \
    -v ~/.cache/electron-builder:/root/.cache/electron-builder \
    -e DEMO_BUILD=1 \
    -e DEMO_EXPIRES=2026-07-26T00:00:00 \
    -e HOST_UID="$HOST_UID" \
    -e HOST_GID="$HOST_GID" \
    electronuserland/builder:wine \
    /bin/bash -c '
        set -e
        fix_owner() {
            chown -R "$HOST_UID:$HOST_GID" \
                node_modules out dist \
                /root/.cache/electron /root/.cache/electron-builder 2>/dev/null || true
        }
        trap fix_owner EXIT

        # Electron 바이너리(protect 단계)가 로드하는 GUI 공유 라이브러리. 이미 있으면 건너뛴다.
        apt-get update
        apt-get install -y --no-install-recommends \
            libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libgtk-3-0 libgbm1 \
            libnss3 libxss1 libasound2 libxshmfence1 libxkbcommon0 libatspi2.0-0 \
            libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libpango-1.0-0 libcairo2

        npm ci
        npm run build
        npm run protect
        npx electron-builder --win
    '

Troubleshooting

The SUID sandbox helper binary was found, but is not configured correctly

dev server running for the electron renderer process at:

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

start electron app...

[51481:0623/152027.976655:FATAL:setuid_sandbox_host.cc(163)] The SUID sandbox helper binary was found, but is not configured correctly. Rather than run without sandboxing I'm aborting now. You need to make sure that /home/zer0/Projects/file-probe/node_modules/electron/dist/chrome-sandbox is owned by root and has mode 4755.

This is a permission issue with Electron's chrome-sandbox SUID binary on Linux. The OS-level sandbox helper of the Electron process itself must be owned by root:root with mode 4755, and the error occurs when it is not (this is separate from the webPreferences.sandbox setting).

Recommended fix (keep the sandbox)

sudo chown root:root node_modules/electron/dist/chrome-sandbox && sudo chmod 4755 node_modules/electron/dist/chrome-sandbox

Then run ./npm run dev again. This approach is recommended because it keeps the sandbox baseline in docs/rules/security.md intact.

However, if electron is reinstalled by ./npm install, the permissions are reset and you may need to run it again.

Alternative (environments without sudo, development only)

If you can't use root privileges, you can disable the OS sandbox only when running in development:

ELECTRON_DISABLE_SANDBOX=1 ./npm run dev

This is only a temporary workaround for development convenience; it does not touch the distribution build (./npm run package) or the code (webPreferences.sandbox: true).

See also

• Squirrel
• TAURI
• NodeGui
• Photino
• Meteor
• Pywebview (python)
  • Neutron
• Tauri - A desktop web app framework that produces small, fast executables
• WebUI - Use any web browser as GUI, with your preferred language in the backend, and HTML/JS/TS/CSS in the frontend.
• Electrobun - Cross-platform desktop applications written in TypeScript

Favorite site

• Electron web site
• Building desktop apps with Electron the way you build web apps
• Building an Electron application
• Electron + AngularJS - Creating sample application
• Creating Desktop Applications With AngularJS and GitHub Electron
• How to load JavaScript libraries in Electron
• Create a Desktop App with Angular 2 and Electron

Guide

• Getting started with Electron
• Electron and C++ dll
• Using custom node packages in Electron
• [Recommended] Electron 3 Building an elegant desktop app with electron-vue ToDo

Deploy guide

• Github - Electron application-distribution (ko)