Introduction

Gelectron is a drop-in replacement for Electron that uses the OS platform WebView (WKWebView / WebView2 / WebKitGTK) instead of Chromium, with a Rust core for native operations. The goal is to provide the same developer experience with smaller binaries and lower memory usage.

Prerequisites

• Rust — stable toolchain 1.75+ (rustup.rs)
• Node.js — 18 or newer
• npm — comes with Node.js
• Git — for cloning the repo

rustc --version    # should be 1.75+
node --version     # should be 18+
npm --version

Installation

git clone https://github.com/mileswolfallen2/gelectron.git
cd gelectron
npm install

cargo build --release -p gelectron

The first build will take a while — the Rust toolchain compiles tao and wry. Subsequent builds are much faster.

Quick Start

The fastest way to see Gelectron running:

cargo run --release -p gelectron -- demo/

This opens a window with an interactive demo app running HTML, CSS, JavaScript, canvas animations, and a live clock.

To run your own Electron app:

cargo run --release -p gelectron -- /path/to/your/electron-app

CLI Reference

Node.js Fallback

If you don't want to build the Rust binary, the CLI can fall back to a pure Node.js shim:

node cli/gelectron.js /path/to/electron-app

In fallback mode no real window is created — only the JS API layer loads. Use the native binary for actual rendering.

Running Apps

Gelectron reads your app's package.json to find the main script, just like Electron does. Your existing Electron code should work without changes for basic apps.

{
  "name": "my-app",
  "main": "main.js"
}

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

app.whenReady().then(() => {
  const win = new BrowserWindow({ width: 800, height: 600 });
  win.loadFile(path.join(__dirname, 'index.html'));
});

app.on('window-all-closed', () => app.quit());

Then run it:

cargo run --release -p gelectron -- .

Demo App

The included demo showcases Gelectron's capabilities:

• Interactive counter (DOM updates via JS)
• Live clock driven by requestAnimationFrame
• Animated canvas with moving shapes
• CSS grid, gradients, transitions, and flexbox

demo/
├── package.json    # { "main": "main.js" }
├── main.js         # Creates BrowserWindow, loads index.html
└── index.html      # HTML + CSS + JavaScript

Packaging for Distribution

Use gelectron-packager to build standalone executables:

# Install the packager
cd packager && npm link && cd ..

# Package for current platform
gelectron-packager --dir ./my-app --name MyApp

# Package for specific platforms
gelectron-packager --dir ./my-app --name MyApp --platform darwin --arch arm64
gelectron-packager --dir ./my-app --name MyApp --platform win32 --arch x64
gelectron-packager --dir ./my-app --name MyApp --platform linux --arch x64

The packager creates a self-contained distributable with the Rust binary, a bundled Node.js runtime (~20 MB), your app source, node_modules, and the Electron compatibility layer.

Main Process Modules

These modules are available via require('electron') in the main process.

Renderer Process Modules

Common Modules

These modules are available in both main and renderer processes.

Deprecated / Internal

Missing Modules

These modules have not been started.

How It Works

Gelectron has two execution paths:

1. Native Binary (recommended)

A standalone Rust binary using tao (windowing) and wry (WebView). It:

1. Reads the target app's package.json to find the main script
2. Generates a Node.js setup script that patches require('electron') to point at Gelectron's JS compatibility layer
3. Spawns Node.js as a child process with piped stdin/stdout
4. Runs a tao event loop with wry WebView windows
5. Communicates with Node.js via JSON-line IPC

2. Node.js Fallback

When the native binary is not built, the CLI falls back to pure Node.js:

1. Patches Module._resolveFilename so require('electron') resolves to Gelectron's shim
2. Loads the app's main script — the app runs against the JS compatibility layer
3. No real window is created (API-only mode)

Project Structure

gelectron/
├── Cargo.toml                    # Rust workspace root
├── package.json                  # npm package
├── cli/
│   └── gelectron.js              # CLI entry point (Node.js fallback)
├── src/electron/                 # JS Electron compatibility layer
│   ├── index.js                  # Main exports
│   ├── app.js                    # app lifecycle
│   ├── browser-window.js         # BrowserWindow + WebContents
│   ├── ipc-main.js              # ipcMain
│   ├── ipc-renderer.js          # ipcRenderer
│   ├── menu.js                  # Menu + MenuItem
│   ├── tray.js                  # Tray
│   ├── dialog.js                # File/message dialogs
│   ├── shell.js                 # Shell operations
│   ├── notification.js          # Notifications
│   ├── native-image.js          # Image handling
│   ├── context-bridge.js        # contextBridge
│   └── auto-updater.js          # autoUpdater (real implementation)
├── crates/
│   ├── gelectron-core/          # N-API addon (Rust → Node.js)
│   └── gelectron-app/           # Standalone native binary
├── demo/                        # Demo app
├── packager/                    # gelectron-packager CLI
└── npm/darwin-arm64/            # Platform-specific npm packages

Environment Variables

Contributing

1. Fork the repo
2. Create a feature branch
3. Make your changes
4. Build and test: cargo build --release -p gelectron
5. Test with the demo: cargo run --release -p gelectron -- demo/
6. Submit a PR

Known Limitations

• Servo not fully embedded — current WebView uses platform native (WebKit on macOS, WebView2 on Windows, webkit2gtk on Linux)
• No Node.js in renderer — all Node.js code runs in the main process only
• Auto-updater is packaged-app only — real checks/downloads/installs for packaged apps with a hosted feed; no-op in development and Node.js fallback mode
• Single-window only in the standalone binary
• Preload scripts are injected via WebView init scripts, not true Electron preload isolation
• Some APIs are stubs — see the API reference for details