OmniRoute/docs/i18n/cs/electron/README.md

Aplikace OmniRoute Electron pro stolní počítače

Tento adresář obsahuje obalovou aplikaci Electron pro desktopovou aplikaci OmniRoute.

Architektura (v1.6.4)

electron/
├── main.js          # Main process — window, tray, server lifecycle, CSP, IPC
├── preload.js       # Preload script — secure IPC bridge with disposer pattern
├── package.json     # Electron-specific dependencies & electron-builder config
├── types.d.ts       # TypeScript definitions (AppInfo, ServerStatus, ElectronAPI)
└── assets/          # Application icons and resources

src/shared/hooks/
└── useElectron.ts   # React hooks — useSyncExternalStore, zero re-renders

Klíčová rozhodnutí o designu

Rozhodnutí	Odůvodnění
dotazování waitForServer()	Zabraňuje zobrazení prázdné obrazovky při studeném startu — před načtením se ozve http://localhost:PORT
stdio: 'pipe'	Zachycuje stdout/stderr serveru pro logování + detekci připravenosti ( inherit )
Vzor drtiče odpadu	onServerStatus() vrací () => void pro přesné vyčištění listeneru (ne removeAllListeners )
useSyncExternalStore	Nulové renderování pro useIsElectron() — žádný cyklus useState + useEffect
CSP prostřednictvím záhlaví relace	Content-Security-Policy omezuje script-src , connect-src atd. dle osvědčených postupů Electron.
Podmíněný titulek pro platformu	titleBarStyle: 'hiddenInset' pouze v systému macOS; default ve Windows/Linuxu

Rozvoj

Předpoklady

1. Nejprve sestavte aplikaci Next.js:

npm run build

1. Instalace závislostí Electronu:

cd electron
npm install

Spuštěno ve vývoji

1. Spusťte vývojový server Next.js:

npm run dev

1. V jiném terminálu spusťte Electron:

cd electron
npm run dev

Spuštění v produkčním režimu

1. Sestavení Next.js v samostatném režimu:

npm run build

1. Spuštění elektronu:

cd electron
npm start

Budova

Sestavení pro aktuální platformu

cd electron
npm run build

Vytvořte pro specifické platformy

# Windows
npm run build:win

# macOS (x64 + arm64)
npm run build:mac

# Linux
npm run build:linux

Výstup

Vytvořené aplikace jsou umístěny v dist-electron/ :

• Windows: .exe instalační program (NSIS) + přenosný .exe
• macOS: instalační soubor .dmg (Intel + Apple Silicon)
• Linux: .AppImage

Instalace

macOS

1. Stáhněte si nejnovější soubor .dmg ze stránky Verze .
2. Otevřete soubor .dmg .
3. Přetáhněte OmniRoute.app do složky Aplikace.
4. Spustit z Aplikací.

⚠️ Poznámka: Aplikace zatím není podepsána certifikátem Apple Developer. Pokud macOS aplikaci blokuje, spusťte:

xattr -cr /Applications/OmniRoute.app

Nebo klikněte pravým tlačítkem myši na aplikaci → Otevřít → Otevřít (pro obejití Gatekeeperu při prvním spuštění).

Windows

Instalační program (doporučeno):

1. Stáhněte si OmniRoute.Setup.*.exe z Releases .
2. Spusťte instalační program.
3. Spuštění z nabídky Start nebo zástupce na ploše.

Přenosné (bez instalace):

1. Stáhněte si soubor OmniRoute.exe ze sekce Vydání .
2. Spouštět přímo z libovolné složky.

Linux

1. Stáhněte si soubor .AppImage ze sekce Releases .
2. Udělejte z něj spustitelný soubor:

   chmod +x OmniRoute-*.AppImage
   

3. Běh:

   ./OmniRoute-*.AppImage
   

Funkce

• Připravenost serveru – Před zobrazením okna čeká na kontrolu stavu
• Systémový zásobník — Minimalizace do systémového zásobníku s rychlými akcemi (otevřít, změnit port, ukončit)
• Správa portů — Změna portu z nabídky v systémové liště (server se automaticky restartuje)
• Ovládací prvky oken — Vlastní minimalizace, maximalizace, zavření přes IPC
• Zásady zabezpečení obsahu – Omezující CSP prostřednictvím záhlaví relací
• Offline podpora — Samostatný server Next.js v balíčku
• Jedna instance – V daném okamžiku může běžet pouze jedna instance aplikace.

Konfigurace

Proměnné prostředí

Proměnná	Výchozí	Popis
OMNIROUTE_PORT	20128	Port serveru
OMNIROUTE_MEMORY_MB	512	Limit haldy Node.js (64–16384 MB)
NODE_ENV	production	Nastavit na development pro vývojářský režim

Vlastní ikona

Umístěte ikony do assets/ :

• icon.ico — ikona Windows (256×256)
• icon.icns — balíček ikon pro macOS
• icon.png — Linux/obecné použití (512×512)
• tray-icon.png — Ikona na systémové liště (16×16 nebo 32×32)

Kanály IPC

Vyvolání (Renderer → Hlavní, asynchronní)

Kanál	Vrácení zboží	Popis
get-app-info	AppInfo	Název aplikace, verze, platforma, isDev, port
open-external	void	Otevřít URL ve výchozím prohlížeči (pouze http/https)
get-data-dir	string	Získat cestu k adresáři userData
restart-server	{ success }	Zastavení + restart serveru (časový limit 5 s + SIGKILL)

Odeslat (Renderer → Hlavní, spustit a zapomenout)

Kanál	Popis
window-minimize	Minimalizovat okno
window-maximize	Přepnout maximalizaci/obnovení
window-close	Zavřít okno (minimalizovat do zásobníku)

Příjem (Hlavní → Renderer, události)

Kanál	Užitečné zatížení	Vydáno, když
server-status	ServerStatus	Server se spouští, zastavuje, dochází k chybám nebo se restartuje
port-changed	number	Změna portu přes menu zásobníku

Poznámka : Posluchače vracejí funkce pro přesné čištění. Viz hooky useServerStatus a usePortChanged .

Zabezpečení

Funkce	Implementace
Izolace kontextu	contextIsolation: true — renderer nemůže přistupovat k Node.js
Integrace uzlů	nodeIntegration: false — v rendereru není require()
Bílý seznam IPC	Názvy kanálů ověřené při předběžném načítání pomocí safeInvoke / safeSend / safeOn
Ověření URL adresy	shell.openExternal() povoluje pouze protokoly http: / https:
CSP	Záhlaví Content-Security-Policy nastavené pomocí session.webRequest.onHeadersReceived
Zabezpečení webu	webSecurity: true – vynucena politika stejného původu

React Hooky

Háček	Vrácení zboží	Popis
useIsElectron()	boolean	Detekce nulového renderování pomocí useSyncExternalStore
useElectronAppInfo()	{ appInfo, loading, error }	Informace o aplikaci z hlavního procesu
useDataDir()	{ dataDir, loading, error }	Adresář uživatelských dat
useWindowControls()	{ minimize, maximize, close }	Akce ovládání oken
useOpenExternal()	{ openExternal }	Otevřít URL adresy v prohlížeči
useServerControls()	{ restart, restarting }	Řízení restartu serveru
useServerStatus(cb)	Drtič odpadu	Poslouchejte události stavu serveru
usePortChanged(cb)	Drtič odpadu	Poslouchejte události změny portu

Odstraňování problémů

Aplikace se nespustí

1. Zkontrolujte, zda je port 20128 dostupný: lsof -i :20128
2. Zkontrolujte protokoly konzole pro prefix [Electron]
3. Ověřte, zda výstup sestavení existuje v souboru .next/standalone

Bílá obrazovka

1. Ověření existence buildu Next.js – čekání na připravenost serveru maximálně 30 sekund
2. Zkontrolujte výstup protokolů [Server] a [Server:err]
3. Hledání porušení CSP v konzoli pro vývojáře

Selhání sestavení

Ujistěte se, že máte nainstalované nástroje pro sestavení:

• Windows: Nástroje pro sestavení ve Visual Studiu
• macOS: Nástroje příkazového řádku Xcode
• Linux: build-essential , libsecret-1-dev

Licence

MIT