Electron Desktop App - Polaris IDE

Overview

Polaris IDE supports Electron for native desktop experiences on Windows, macOS, and Linux.

The Electron app bundles a local Next.js server for offline-capable editing with cloud sync.

Architecture

The Electron app consists of:

Main Process

Node.js backend handling:

Window management
File system operations
IPC communication
Auto-updates

Renderer Process

Chromium frontend running:

Next.js application
React components
CodeMirror editor

Development Setup

Prerequisites

Complete web setup

Follow the Setup Guide first - the Electron app requires a working Next.js application.

Install Electron dependencies

npm install

Key dependencies:

electron - Framework
electron-builder - Packaging and distribution
electron-store - Persistent storage
electron-updater - Auto-update support
electron-log - Logging

Running in Development

# Start Electron development mode
npm run electron:dev

This command:

Starts Next.js dev server on port 3000
Compiles TypeScript in electron/ directory
Launches Electron pointing to localhost:3000

The app will hot-reload when you make changes to frontend code, but requires restart for Electron main process changes.

Project Structure

electron/
├── main/
│   ├── index.ts           # Main process entry point
│   ├── window.ts          # Window creation and management
│   ├── ipc-handlers.ts    # IPC communication handlers
│   ├── auto-updater.ts    # Update logic
│   └── menu.ts            # Application menu
├── preload/
│   └── index.ts           # Preload script (bridge)
├── resources/
│   ├── icons/             # App icons
│   │   ├── icon.icns        # macOS
│   │   ├── icon.ico         # Windows
│   │   └── icon.png         # Linux
│   └── installer/         # Installer assets
└── tsconfig.json        # TypeScript config for Electron

Building for Production

Build Configuration

The build process is configured in electron-builder.yml:

electron-builder.yml

appId: com.polaris.ide
productName: Polaris IDE
copyright: Copyright © 2025 Polaris Team

directories:
  buildResources: electron/resources
  output: dist-electron

files:
  - "!**/.git/**"
  - "!src/**"
  - "!tests/**"
  - "!.next/cache/**"
  - "dist-electron/main/**/*.js"
  - "dist-electron/preload/**/*.js"
  - ".next/standalone/**"
  - ".next/static/**"
  - "public/**"
  - "package.json"

extraResources:
  - from: ".next/standalone"
    to: "server"
  - from: ".next/static"
    to: "server/.next/static"
  - from: "public"
    to: "server/public"

Build Commands

All Platforms
Windows Only
macOS Only
Linux Only

# Build for all platforms
npm run electron:build

This creates distributables for:

Windows (NSIS installer)
macOS (DMG)
Linux (AppImage, deb, rpm)

npm run electron:build:win

Creates:

Polaris IDE Setup.exe - NSIS installer
Portable version (optional)

npm run electron:build:mac

Creates:

Polaris IDE.dmg - Disk image
Polaris IDE.app - Application bundle

macOS builds require running on macOS with Xcode installed

npm run electron:build:linux

Creates:

polaris-ide-x.x.x.AppImage
polaris-ide_x.x.x_amd64.deb
polaris-ide-x.x.x.rpm

Build Process Details

Build Next.js for standalone

# Triggered by: npm run electron:build:next
cross-env BUILD_ELECTRON=true next build

This creates:

.next/standalone/ - Minimal Node.js server
.next/static/ - Static assets

Compile TypeScript

# Triggered by: npm run electron:compile
tsc -p electron/tsconfig.json

Outputs to dist-electron/

Package with electron-builder

electron-builder

Creates platform-specific installers in dist-electron/

Platform-Specific Configuration

Windows

electron-builder.yml

win:
  target:
    - target: nsis
      arch:
        - x64
  icon: electron/resources/icons/icon.ico
  publisherName: Polaris Team

nsis:
  oneClick: false
  allowToChangeInstallationDirectory: true
  createDesktopShortcut: always
  createStartMenuShortcut: true
  perMachine: false

Code Signing

For production releases, sign your Windows executable:

Obtain a code signing certificate

Set environment variables:

set WIN_CSC_LINK=path/to/certificate.pfx
set WIN_CSC_KEY_PASSWORD=your_password

Build with signing:
```
npm run electron:build:win
```

Installer Options

Customize NSIS installer:

nsis:
  oneClick: false              # Allow custom install location
  allowElevation: true         # Request admin privileges
  perMachine: false            # Install per-user by default
  allowToChangeInstallationDirectory: true
  installerIcon: "icon.ico"
  uninstallerIcon: "icon.ico"
  createDesktopShortcut: always
  createStartMenuShortcut: true
  shortcutName: "Polaris IDE"

macOS

electron-builder.yml

mac:
  target:
    - dmg
    - zip
  icon: electron/resources/icons/icon.icns
  category: public.app-category.developer-tools
  hardenedRuntime: true
  gatekeeperAssess: false
  entitlements: electron/resources/entitlements.mac.plist
  entitlementsInherit: electron/resources/entitlements.mac.plist

dmg:
  sign: false
  contents:
    - x: 130
      y: 220
    - x: 410
      y: 220
      type: link
      path: /Applications

Code Signing & Notarization

Required for distribution outside App Store:

Join Apple Developer Program ($99/year)
Create certificates in Xcode

Set environment variables:

export APPLE_ID=your@email.com
export APPLE_APP_SPECIFIC_PASSWORD=xxxx-xxxx-xxxx-xxxx
export APPLE_TEAM_ID=XXXXXXXXXX

Build with signing:
```
npm run electron:build:mac
```

electron-builder will automatically notarize the app.

Entitlements

Create electron/resources/entitlements.mac.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>com.apple.security.cs.allow-jit</key>
    <true/>
    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
    <true/>
    <key>com.apple.security.cs.allow-dyld-environment-variables</key>
    <true/>
  </dict>
</plist>

Linux

electron-builder.yml

linux:
  target:
    - AppImage
    - deb
    - rpm
  icon: electron/resources/icons/
  category: Development
  mimeTypes:
    - x-scheme-handler/polaris
  executableName: polaris-ide

AppImage

Universal Linux binary:

No installation required
Runs on most distributions
Includes all dependencies

Usage:

chmod +x polaris-ide-x.x.x.AppImage
./polaris-ide-x.x.x.AppImage

Debian Package

For Debian/Ubuntu:

sudo dpkg -i polaris-ide_x.x.x_amd64.deb

RPM Package

For Fedora/RHEL/CentOS:

sudo rpm -i polaris-ide-x.x.x.rpm

Auto-Updates

Configure Update Server

electron-builder.yml

publish:
  provider: github
  owner: Jackson57279
  repo: polaris
  releaseType: release

Implement Update Logic

electron/main/auto-updater.ts

import { autoUpdater } from 'electron-updater';
import log from 'electron-log';

export function setupAutoUpdater(mainWindow: BrowserWindow) {
  // Configure logging
  autoUpdater.logger = log;
  
  // Check for updates on startup
  autoUpdater.checkForUpdatesAndNotify();
  
  // Check every 4 hours
  setInterval(() => {
    autoUpdater.checkForUpdatesAndNotify();
  }, 4 * 60 * 60 * 1000);
  
  // Events
  autoUpdater.on('update-available', (info) => {
    mainWindow.webContents.send('update-available', info);
  });
  
  autoUpdater.on('update-downloaded', (info) => {
    mainWindow.webContents.send('update-downloaded', info);
  });
}

Handle Updates in Frontend

src/app/layout.tsx

import { useEffect } from 'react';
import { toast } from 'sonner';

function ElectronUpdater() {
  useEffect(() => {
    if (!window.electron) return;
    
    window.electron.on('update-available', () => {
      toast.info('Update available', {
        description: 'Downloading in background...'
      });
    });
    
    window.electron.on('update-downloaded', () => {
      toast.success('Update ready', {
        description: 'Restart to apply update',
        action: {
          label: 'Restart',
          onClick: () => window.electron.restartApp()
        }
      });
    });
  }, []);
  
  return null;
}

Distribution

GitHub Releases

Create release

git tag v1.0.0
git push origin v1.0.0

Build artifacts

npm run electron:build

Upload to GitHub

Go to GitHub Releases
Create new release for tag
Upload files from dist-electron/:
- Polaris-IDE-Setup-x.x.x.exe
- Polaris-IDE-x.x.x.dmg
- polaris-ide-x.x.x.AppImage
- latest.yml (for auto-updates)

Other Distribution Channels

Microsoft Store

Submit to Windows Store for wider reach

Mac App Store

Distribute via Apple’s App Store

Snap Store

Linux distribution via Snapcraft

Homebrew

macOS package manager for developers

Offline Support

The Electron app can work offline:

Local Storage

import Store from 'electron-store';

const store = new Store({
  name: 'polaris-data',
  defaults: {
    projects: [],
    settings: {}
  }
});

// Save project locally
store.set('projects', projects);

// Sync to Convex when online
if (navigator.onLine) {
  await syncToConvex(projects);
}

Offline Detection

window.addEventListener('online', async () => {
  toast.success('Back online - syncing changes...');
  await syncLocalChanges();
});

window.addEventListener('offline', () => {
  toast.warning('Working offline - changes will sync when reconnected');
});

Troubleshooting

Build fails on Windows

Issue: electron-builder failsSolutions:

Install Windows Build Tools:

npm install --global windows-build-tools

Use Node.js 20.x (LTS)
Run as Administrator if permission errors

macOS code signing errors

Issue: Notarization failsSolutions:

Ensure valid Apple Developer account
Check certificate validity in Keychain
Verify app-specific password is correct
Check entitlements file exists

Linux AppImage won't run

Issue: Permission deniedSolution:

chmod +x polaris-ide-x.x.x.AppImage

Auto-update not working

Issue: Updates not detectedSolutions:

Check latest.yml exists in release
Verify GitHub repository settings in electron-builder.yml
Ensure app is signed (required for auto-update)
Check console for update errors

Next Steps

Web Deployment

Deploy web version to Vercel

Architecture

Understand the system design

Contributing

Contribute to Polaris

Error Tracking

Monitor desktop app errors

Development

Deployment

Advanced

​Overview

​Architecture

Main Process

Renderer Process

​Development Setup

​Prerequisites

​Running in Development

​Project Structure

​Building for Production

​Build Configuration

​Build Commands

​Build Process Details

​Platform-Specific Configuration

​Windows

​macOS

​Linux

​Auto-Updates

​Configure Update Server

​Implement Update Logic

​Handle Updates in Frontend

​Distribution

​GitHub Releases

​Other Distribution Channels

Microsoft Store

Mac App Store

Snap Store

Homebrew

​Offline Support

​Local Storage

​Offline Detection

​Troubleshooting

​Next Steps

Web Deployment

Architecture

Contributing

Error Tracking

Build docs developers (and LLMs) love

Overview

Architecture

Development Setup

Prerequisites

Running in Development

Project Structure

Building for Production

Build Configuration

Build Commands

Build Process Details

Platform-Specific Configuration

Windows

macOS

Linux

Auto-Updates

Configure Update Server

Implement Update Logic

Handle Updates in Frontend

Distribution

GitHub Releases

Other Distribution Channels

Offline Support

Local Storage

Offline Detection

Troubleshooting

Next Steps