Angular + Electron: запуск в окне рабочего стола

Если вы хотите запускать существующее Angular‑приложение не в браузере, а в окне настольного приложения — используйте Electron. В статье описаны шаги: установка Node.js и Electron, создание main.js, правки index.html и package.json, запуск через npm run electron. Приведены чеклисты, тесты и рекомендации по совместимости.

Разработчик пишет код на компьютере

Electron позволяет упаковать веб‑приложение в настольное приложение для Windows, macOS и Linux. Для Angular‑проекта это означает: добавить в репозиторий небольшой JavaScript‑файл (обычно main.js), который создаёт окно рабочего стола и загружает в него скомпилированный index.html из папки dist.

Важно: структура приложения Angular остаётся стандартной — вы продолжаете работать с компонентами, сервисами и сборкой так же, как и раньше.

Кому это подойдет

Разработчикам, которые хотят предоставить десктопную версию без переписывания фронтенда.
Командам, которым нужен доступ к нативным возможностям ОС (файловая система, нотификации) через Electron API.

Вводные термины

Electron — фреймворк для создания настольных приложений на базе Chromium + Node.js.
main.js — «главный» файл Electron, запускающий окно приложения.

Что нужно подготовить перед началом

Установленный Node.js (включает npm).
Существующий Angular‑проект или новый, созданный через ng new.
Базовые навыки работы с терминалом и package.json.

Как установить Electron в проект

Скачайте и установите Node.js. Проверьте версии:

node -v

npm (поставляется вместе с Node.js):

npm -v

Создайте новый Angular‑проект (или используйте существующий):

ng new electron-app

Установите Electron в корне проекта (локально в devDependencies):

npm install --save-dev electron

После установки появится папка Electron в node_modules.

Папка Electron в node_modules

При желании можно установить Electron глобально (опция):

npm install -g electron

Примечание: глобальная установка удобна для тестов, но для сборки/CI рекомендована локальная dev‑зависимость.

Структура файлов Angular + Electron

Electron ожидает «главный» JS‑файл, который создаёт BrowserWindow и загружает index.html из папки dist. В Angular исходный index.html находится в src, а при сборке копируется в dist//index.html.

Расположение main.js внутри проекта

Расположение index.html в проекте

Пример стандартного index.html из Angular:




  
   ElectronApp

Тег будет рендерить главный компонент приложения (src/app).

Расположение главного компонента приложения

Создание main.js и открытие окна приложения

Создайте файл main.js в корне проекта и добавьте минимальную логику для создания окна:

Инициализируйте Electron:

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

Создайте окно и загрузите index.html из dist (замените electron-app на имя вашей сборки):

function createWindow() {
  win = new BrowserWindow({width: 800, height: 800});
  win.loadFile('dist/electron-app/index.html');
}

Создайте окно при готовности приложения:

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

Дополнительно: обработайте событие закрытия окон и поведение для macOS, если нужно. Это стандартные практики Electron (app.on(‘window-all-closed’), app.on(‘activate’)).

Обязательные правки в проекте

В src/index.html установите в относительный путь:

В package.json добавьте поле main, указывающее на main.js:

{
  "name": "electron-app",
  "version": "0.0.0",
  "main" : "main.js",
  ....
}

В .browserslistrc уберите проблемные версии Safari/iOS, чтобы избежать предупреждений сборки:

last 1 Chrome version
last 1 Firefox version
last 2 Edge major versions
last 2 Safari major versions
last 2 iOS major versions
Firefox ESR
not ios_saf 15.2-15.3
not safari 15.2-15.3

Замените содержимое src/app/app.component.html на простую разметку для старта:


  
     Home 
    
      Welcome to my Angular Electron application!

Добавьте локальные стили в src/app/app.component.css:

.content {
  line-height: 2rem;
  font-size: 1.2em;
  margin: 48px 10%;
  font-family: Arial, sans-serif
}
.card {
  box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2);
  width: 85%;
  padding: 16px 48px;
  margin: 24px 0px;
  background-color: whitesmoke;
  font-family: sans-serif;
}

Удалите отступы браузера в глобальном CSS (src/styles.css):

html {
  margin: 0;
  padding: 0;
}

Скрипт запуска и запуск приложения

Добавьте в package.json скрипт, который сначала соберёт Angular, затем запустит Electron:

"scripts": {
  ...
  "electron": "ng build && electron ."
},

Запуск из корня проекта:

npm run electron

После сборки вместо открытия в браузере откроется настольное окно с вашим приложением.

Electron во время выполнения в окне рабочего стола

Если нужно тестировать в браузере, используйте:

ng serve

При ng serve приложение будет доступно по адресу http://localhost:4200

Electron во время выполнения в браузере

Полезные советы и распространённые ошибки

Important: всегда проверяйте путь, который вы передаёте в win.loadFile(). Путь должен указывать на итоговый index.html в папке dist после ng build.

Notes:

Если окно открывается, но в нём пусто — проверьте, собрался ли проект и существует ли файл dist/electron-app/index.html.
Для доступа к Node API в рендере применяйте препроцессоры или contextBridge—не оставляйте nodeIntegration:true без понимания рисков безопасности.
Для упаковки окончательного приложения используйте electron-builder или electron-packager.

Когда такой подход не подойдёт (контрпримеры)

Если нужно полностью нативный интерфейс с элементами управления ОС, которые нельзя реализовать через HTML/CSS — лучше использовать нативные фреймворки.
Если приложение должно быть максимально лёгким по потреблению ресурсов, Electron может быть слишком тяжёлым (Chromium включён в сборку).

Альтернативные подходы

Тонкие клиенты: оставить веб‑версию и предоставлять десктопный лаунчер, который открывает страницу в WebView.
Нативные кроссплатформенные фреймворки: Flutter Desktop, .NET MAUI, Qt.

Чеклист перед публикацией (разработчик)

Проверить, что win.loadFile указывает на правильный путь.
Проверить production‑сборку ng build –prod (или эквивалент для текущей версии Angular).
Проверить обработчики закрытия окна и поведения на macOS.
Отключить nodeIntegration в рендере и использовать безопасные мосты (contextBridge) для доступа к Node.
Настроить electron-builder или packager для формирования инсталляторов.

Чеклист для QA

Открывается ли приложение на Windows, macOS, Linux (по приоритету)?
Работает ли меню, хоткеи и диалоги открытия/сохранения?
Нет ли ошибок в консоли DevTools при загрузке приложения?
Корректно ли работают обновления (если реализованы)?

Тестовые сценарии и критерии приёмки

Сценарий: запуск приложения из npm run electron
- Шаги: выполнить npm run electron в корне проекта.
- Ожидаемое: открылось окно Electron, отображается содержимое приложения.
Сценарий: запуск ng serve
- Ожидаемое: приложение доступно по http://localhost:4200 и работает как в обычном веб‑приложении.
Сценарий: отсутствие dist/electron-app/index.html
- Ожидаемое: приложение не запускается; в логах — сообщение об отсутствии файла. Ошибка должна быть информативной.

Модель принятия решений (Mermaid)

flowchart TD
  A[Есть готовый Angular‑проект?] -->|Да| B{Требуется нативный UI?}
  A -->|Нет| Z[Создать проект через ng new]
  B -->|Да| C[Рассмотреть Flutter/Desktop или .NET MAUI]
  B -->|Нет| D[Использовать Electron]
  D --> E[Добавить main.js и правки index.html]
  E --> F[Тестировать npm run electron]

Совместимость и миграционные заметки

Убедитесь, что версия Electron совместима с версией Node.js, используемой в проекте. При возникновении проблем с бинарными модулями — пересоберите зависимости.
Для сборки под macOS требуются CI‑агенты на macOS или локальная машина с macOS.
Если проект использует специфичные веб‑API или experimental features, проверьте их поддержку в встроенном Chromium (версию Chromium можно узнать в выходе electron –version или в процессах приложения).

Безопасность и приватность

Отключайте nodeIntegration в рендере, если не контролируете содержимое, загружаемое в окно.
Используйте contextBridge для безопасной передачи ограничённых API в рендер.
Если приложение обрабатывает персональные данные, соблюдайте требования местного законодательства о защите данных (например, GDPR в ЕС). Хранение и передача данных не меняются только из‑за упаковки в Electron.

Короткая методика упаковки (mini‑methodology)

Подготовьте production‑сборку: ng build –configuration production
Проверьте main.js и пути к dist
Добавьте скрипты для electron: npm run electron (разработка)
Настройте electron-builder для создания установщиков: npm install –save-dev electron-builder; добавьте конфигурацию в package.json
Запустите сборку установщика и протестируйте на целевых ОС

Шаблон package.json — минимальный пример

{
  "name": "electron-app",
  "version": "0.0.0",
  "main": "main.js",
  "scripts": {
    "ng": "ng",
    "start": "ng serve",
    "build": "ng build",
    "electron": "ng build && electron ."
  },
  "devDependencies": {
    "electron": "<ваша-версия>"
  }
}

Не забудьте заменить <ваша-версия> на конкретную версию Electron в ваших devDependencies.

Глоссарий — 1 строка

BrowserWindow — API Electron для создания окна, которое рендерит HTML/CSS/JS.

Когда нужно перейти на нативный путь

Если вы планируете плотную интеграцию с ОС (скрипты установки привилегий, драйверами, высокопроизводительная графика), изучите нативные или специализированные платформы вместо Electron.

Короткое объявление для команды (100–200 слов)

Добавили поддержку запуска Angular‑приложения в виде настольного приложения через Electron. Это позволяет тестировать и распространять приложение как обычный десктопный продукт на Windows, macOS и Linux без переписывания фронтенда. Чтобы начать, установите зависимости npm install, добавьте main.js в корень и выполните npm run electron. Приложение будет запускаться из dist//index.html. В статье есть чеклисты для разработчика и QA, рекомендации по безопасности и краткая методика упаковки через electron‑builder.

Краткое резюме

Electron упаковывает Angular‑приложение в окно рабочего стола.
Нужны правки: main.js, base href, поле main в package.json.
Тестирование и безопасность обязательны: отключайте nodeIntegration и используйте contextBridge.

Summary

Electron даёт быстрый путь к десктопной версии веб‑приложения.
Правильная сборка и пути к index.html — самые частые проблемы.
Для выпуска используйте electron‑builder и проверяйте поведение на целевых ОС.

Как открыть Angular‑приложение в окне рабочего стола с помощью Electron