> For AI agents: the complete documentation index is available at /next/llms.txt, the full documentation bundle is available at /next/llms-full.txt.

# Migrating from Electron to Lynxtron

If you already have an Electron app, you can think of the migration to Lynxtron as: **keep as much of the main process and desktop integration as possible, and replace the Chromium Renderer Web UI with Lynx UI**.

Lynxtron's main-process APIs mostly follow Electron. [`LynxWindow`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md), [`Menu`](/next/lynxtron/api/@lynx-js/lynxtron/Class.Menu.md), [`Tray`](/next/lynxtron/api/@lynx-js/lynxtron/Class.Tray.md), [`Notification`](/next/lynxtron/api/@lynx-js/lynxtron/Class.Notification.md), [`dialog`](/next/lynxtron/api/@lynx-js/lynxtron/Variable.dialog.md), [`shell`](/next/lynxtron/api/@lynx-js/lynxtron/Variable.shell.md), [`screen`](/next/lynxtron/api/@lynx-js/lynxtron/Variable.screen.md), and similar desktop APIs are close to their Electron counterparts. The part that needs a real redesign is the UI layer: Lynxtron does not load HTML pages and does not render through the DOM. Window content is driven by a Lynx bundle and rendered with Lynx elements, styles, and runtime DSLs.

## Split the Migration Scope First

Start by splitting the app by runtime layer instead of replacing files one by one:

| Part of an Electron app                                                       | How to migrate it to Lynxtron                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Main-process lifecycle, menus, tray, notifications, dialogs, shell, screen    | Usually reusable with minor changes, using Lynxtron APIs with the same or similar names, such as [`app`](/next/lynxtron/api/@lynx-js/lynxtron/Variable.app.md), [`Menu`](/next/lynxtron/api/@lynx-js/lynxtron/Class.Menu.md), [`Tray`](/next/lynxtron/api/@lynx-js/lynxtron/Class.Tray.md), [`Notification`](/next/lynxtron/api/@lynx-js/lynxtron/Class.Notification.md), [`dialog`](/next/lynxtron/api/@lynx-js/lynxtron/Variable.dialog.md), [`shell`](/next/lynxtron/api/@lynx-js/lynxtron/Variable.shell.md), and [`screen`](/next/lynxtron/api/@lynx-js/lynxtron/Variable.screen.md).                                                                           |
| `BrowserWindow` creation and window options                                   | Replace it with [`LynxWindow`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md). Options such as [`width`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxWindowConstructorOptions.md#width), [`height`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxWindowConstructorOptions.md#height), [`frame`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxWindowConstructorOptions.md#frame), [`transparent`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxWindowConstructorOptions.md#transparent), and [`titleBarStyle`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxWindowConstructorOptions.md#titlebarstyle) are mostly the same. |
| `loadFile('index.html')` / `loadURL()` for Web pages                          | Load a Lynx bundle instead, for example [`win.loadFile(bundlePath)`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md#loadfile).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Renderer HTML, DOM, Web CSS, and Web component libraries                      | Rewrite as Lynx UI. You can use ReactLynx, VueLynx, or other Lynx runtime DSLs, and render with Lynx elements such as [`<view>`](/next/api/elements/built-in/view.md), [`<text>`](/next/api/elements/built-in/text.md), and [`<image>`](/next/api/elements/built-in/image.md).                                                                                                                                                                                                                                                                                                                                                                                       |
| `ipcRenderer` / `ipcMain`                                                     | Migrate by direction to [`LynxWindow.sendGlobalEvent()`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md#sendglobalevent), `NativeModules.bridge.call` / `NativeModules.bridge.send`, and listen for [`-lynx-invoke`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md#event--lynx-invoke) / [`-lynx-message`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md#event--lynx-message) events on the main-process side.                                                                                                                                                                                                                       |
| `webPreferences.preload` / `contextBridge`                                    | Use [`lynxPreference.preload`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxPreference.md#preload) + [`contextBridge.exposeInLynxBTS()`](/next/lynxtron/api/@lynx-js/lynxtron/context-bridge/Interface.ContextBridge.md#exposeinlynxbts) + [`NativeModules.nodejs.exposed`](/next/lynxtron/api/@lynx-js/lynxtron/lynx/Interface.LynxtronNodejs.md#exposed) to expose Node.js capabilities through [preload scripts](/next/lynxtron/learn/Communication-Between-Node-And-Lynx.md#use-preload-scripts).                                                                                                                                                          |
| Node.js native modules built for the Electron ABI                             | Rebuild with [`@lynx-js/lynxtron-rebuild`](/next/lynxtron/api/@lynx-js/lynxtron-rebuild/index.md). See [Node.js Native Modules](/next/lynxtron/Native-Libraries/NodeJS-Native-Modules.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `electron-builder` packaging configuration                                    | Use [`@lynx-js/lynxtron-builder`](/next/lynxtron/api/@lynx-js/lynxtron-builder/index.md) as the packaging entry. You can usually keep `electron-builder.yml`, but make sure the app directory, file list, and Lynx bundle outputs point to the Lynxtron app.                                                                                                                                                                                                                                                                                                                                                                                                         |
| Embedded web content such as `<webview>`, `BrowserView`, or `WebContentsView` | Migrate case by case. If you still need to embed web content in Lynx UI, see the [browser tutorial](/next/lynxtron/learn/introduction_to_browser.md). If the migrated app needs system controls or complex native views, see [Lynx Native Libraries](/next/lynxtron/Native-Libraries/Lynx-Native-Libraries.md).                                                                                                                                                                                                                                                                                                                                                      |

## API Mapping

| Migration target                 | Electron                                                                                         | Lynxtron                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| -------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create a window                  | [`BrowserWindow`](https://www.electronjs.org/docs/latest/api/browser-window)                     | [`LynxWindow`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md)                                                                                                                                                                                                                                                                                                                                                                 |
| Window constructor options       | `new BrowserWindow({ width, height, frame, transparent })`                                       | `new LynxWindow({` [`width`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxWindowConstructorOptions.md#width), [`height`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxWindowConstructorOptions.md#height), [`frame`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxWindowConstructorOptions.md#frame), [`transparent`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxWindowConstructorOptions.md#transparent) `})` |
| Load UI                          | `win.loadFile('index.html')`                                                                     | [`win.loadFile(bundlePath)`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md#loadfile)                                                                                                                                                                                                                                                                                                                                          |
| Configure Preload Scripts        | `webPreferences.preload`                                                                         | [`lynxPreference.preload`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxPreference.md#preload)                                                                                                                                                                                                                                                                                                                                     |
| Expose Node.js capabilities      | `contextBridge.exposeInMainWorld()`                                                              | [`contextBridge.exposeInLynxBTS()`](/next/lynxtron/api/@lynx-js/lynxtron/context-bridge/Interface.ContextBridge.md#exposeinlynxbts)                                                                                                                                                                                                                                                                                                      |
| UI accesses exposed objects      | `window.<api>`                                                                                   | [`NativeModules.nodejs.exposed`](/next/lynxtron/api/@lynx-js/lynxtron/lynx/Interface.LynxtronNodejs.md#exposed)                                                                                                                                                                                                                                                                                                                          |
| Main process pushes events to UI | `webContents.send()`                                                                             | [`LynxWindow.sendGlobalEvent()`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md#sendglobalevent)                                                                                                                                                                                                                                                                                                                               |
| UI calls main process and waits  | `ipcRenderer.invoke()` + `ipcMain.handle()`                                                      | `NativeModules.bridge.call` → [`-lynx-invoke`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md#event--lynx-invoke) event                                                                                                                                                                                                                                                                                                        |
| UI sends one-way messages        | `ipcRenderer.send()` + `ipcMain.on()`                                                            | `NativeModules.bridge.send` → [`-lynx-message`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md#event--lynx-message) event                                                                                                                                                                                                                                                                                                      |
| Rebuild native modules           | [`@electron/rebuild`](https://www.electronjs.org/docs/latest/tutorial/using-native-node-modules) | [`@lynx-js/lynxtron-rebuild`](/next/lynxtron/api/@lynx-js/lynxtron-rebuild/index.md)                                                                                                                                                                                                                                                                                                                                                     |
| Package the app                  | [`electron-builder`](https://www.electron.build/)                                                | [`@lynx-js/lynxtron-builder`](/next/lynxtron/api/@lynx-js/lynxtron-builder/index.md)                                                                                                                                                                                                                                                                                                                                                     |

## Migrate Main-Process Window Creation

A common Electron window setup:

```typescript
import { app, BrowserWindow } from 'electron';
import path from 'path';

app.whenReady().then(() => {
  const win = new BrowserWindow({
    width: 960,
    height: 640,
    frame: false,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
    },
  });

  win.loadFile('index.html');
});
```

In Lynxtron, the main process still runs in Node.js, but the window type and UI entry change:

```typescript
import { app, LynxWindow } from '@lynx-js/lynxtron';
import path from 'path';

app.whenReady().then(() => {
  const win = new LynxWindow({
    width: 960,
    height: 640,
    frame: false,
    lynxPreference: {
      preload: path.join(__dirname, 'preload.js'),
    },
  });

  const bundlePath = path.join(__dirname, 'main.lynx.bundle');
  win.loadFile(bundlePath);
});
```

This example assumes that the built main-process file and `main.lynx.bundle` are in the same directory. Adjust the path to match your build output layout.

Start by carrying over window shape options such as [`width`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxWindowConstructorOptions.md#width), [`height`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxWindowConstructorOptions.md#height), [`frame`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxWindowConstructorOptions.md#frame), [`transparent`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxWindowConstructorOptions.md#transparent), [`titleBarStyle`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxWindowConstructorOptions.md#titlebarstyle), and [`trafficLightPosition`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxWindowConstructorOptions.md#trafficlightposition). For frameless windows, transparent windows, and custom title bars in Lynx UI, see [Building a Custom Window](/next/lynxtron/learn/Custom-Window-Styles.md).

## Rewrite the Renderer UI

Lynxtron does not run the HTML page from the Electron Renderer directly. To migrate UI code, rewrite the DOM structure, Web CSS, and browser event model as Lynx UI.

| Web / Electron Renderer | Lynxtron UI                                                                                                     |
| ----------------------- | --------------------------------------------------------------------------------------------------------------- |
| `<div>` / `<span>`      | [`<view>`](/next/api/elements/built-in/view.md) / [`<text>`](/next/api/elements/built-in/text.md)               |
| `<img>`                 | [`<image>`](/next/api/elements/built-in/image.md)                                                               |
| Web CSS                 | [Lynx styling](https://lynxjs.org/guide/ui/styling.html)                                                        |
| `-webkit-app-region`    | [`-x-app-region`](/next/lynxtron/learn/Custom-Window-Styles.md#define-ui-draggable-regions)                     |
| Custom title-bar DOM    | [`<title-bar-view>`](/next/api/elements/built-in/title-bar-view.md) or Lynx elements with `-x-app-region: drag` |

Events also need to move from React DOM events to Lynx element events. For example, an Electron React button:

```tsx
export function Toolbar() {
  return <button onClick={openFile}>Open</button>;
}
```

After migrating to ReactLynx:

```tsx
export function Toolbar() {
  return (
    <view className="button" bindtap={openFile}>
      <text>Open</text>
    </view>
  );
}
```

If your Electron app depends heavily on DOM APIs, browser layout behavior, Canvas, WebGL, or Web component libraries, treat UI migration as a separate phase. Keep the main-process services and communication protocol first, then rewrite each window with Lynx UI.

### Progressive Migration: Put Existing Web UI in `<webview>` First

If rewriting the entire Renderer UI at once is too expensive, you can build the window shell with Lynx UI first and put Web UI that has not been migrated yet into [`<webview>`](/next/api/elements/built-in/webview.md). This lets you migrate the main process, window creation, packaging, preload scripts, and IPC first while keeping parts of the existing Web pages running.

```tsx
export function LegacyPanel() {
  return (
    <view className="legacy-panel">
      <webview
        className="legacy-webview"
        src="http://127.0.0.1:3000/legacy.html"
        use-osr={true}
        enable-debug={true}
      />
    </view>
  );
}
```

This is useful as a transition strategy:

- Build the window frame, title bar, navigation, global state, and new page entries with Lynx first.
- Temporarily put old pages that rely heavily on the DOM or Web component libraries into `<webview>`.
- After a page is migrated, replace its `<webview>` content with Lynx elements.
- Keep newly migrated main-process capabilities behind Lynxtron bridge or preload scripts, instead of expanding the old Web UI's dependency on Electron Renderer APIs.

Keep in mind that content inside `<webview>` is still Web content. It does not automatically become Lynx UI. This approach is useful for reducing migration risk and splitting the migration into smaller steps, but core desktop UI should still be gradually rewritten with Lynx elements.

## Migrate Preload Scripts and Node.js Exposure

In Electron, a [preload script](https://www.electronjs.org/docs/latest/tutorial/tutorial-preload) often exposes capabilities with `contextBridge.exposeInMainWorld()`:

```typescript
// preload.ts
import { contextBridge, ipcRenderer } from 'electron';

contextBridge.exposeInMainWorld('desktop', {
  readConfig: () => ipcRenderer.invoke('read-config'),
});
```

The Renderer side calls through `window.desktop`:

```typescript
const config = await window.desktop.readConfig();
```

In Lynxtron, the preload script can still use Node.js capabilities, but the exposure target becomes [`NativeModules.nodejs.exposed`](/next/lynxtron/api/@lynx-js/lynxtron/lynx/Interface.LynxtronNodejs.md#exposed) in Lynx BTS:

```typescript
// preload.ts
import { contextBridge } from '@lynx-js/lynxtron/context-bridge';
import fs from 'fs';

contextBridge.exposeInLynxBTS({
  desktop: {
    readConfig: () => {
      return fs.promises.readFile('/path/to/config.json', 'utf8');
    },
  },
});
```

The Lynx UI side calls through [`NativeModules.nodejs.exposed`](/next/lynxtron/api/@lynx-js/lynxtron/lynx/Interface.LynxtronNodejs.md#exposed):

```tsx
const { desktop } = NativeModules.nodejs.exposed;
const config = await desktop.readConfig();
```

Lynxtron [preload scripts](/next/lynxtron/learn/Communication-Between-Node-And-Lynx.md#use-preload-scripts) and Lynx BTS are isolated JS contexts in the same process. [`exposeInLynxBTS()`](/next/lynxtron/api/@lynx-js/lynxtron/context-bridge/Interface.ContextBridge.md#exposeinlynxbts) exposes JS objects that BTS can call directly. These objects can contain functions, closures, and asynchronous APIs that return Promises. For details, see [Node.js and Lynx Communication: Use Preload Scripts](/next/lynxtron/learn/Communication-Between-Node-And-Lynx.md#use-preload-scripts).

## Migrate IPC

If the Electron Renderer calls the main process with `ipcRenderer.invoke()`:

```typescript
// renderer.ts
const result = await ipcRenderer.invoke('get-system-info', {
  includeCpuDetail: true,
});
```

The Lynx UI side uses `NativeModules.bridge.call(method, payload, callback)`. It returns `void`, so receive the reply in the callback instead of directly awaiting the call:

```tsx
// App.tsx
NativeModules.bridge.call(
  'get-system-info',
  { includeCpuDetail: true },
  (result) => {
    renderSystemInfo(result);
  },
);
```

The Node main process listens for the [`-lynx-invoke`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md#event--lynx-invoke) event to handle `bridge.call` calls, and returns the result through `event.sendReply`:

```typescript
// main.ts
// Reuse win inside app.whenReady() above; register this listener before win.loadFile().

win.on('-lynx-invoke', (event, methodName, params) => {
  if (methodName === 'get-system-info') {
    event.sendReply(getSystemInfo(params));
  }
});
```

If the Electron main process pushes events to the Renderer with `webContents.send()`:

```typescript
win.webContents.send('system-info-update', data);
```

Use [`LynxWindow.sendGlobalEvent()`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md#sendglobalevent) in Lynxtron:

```typescript
win.sendGlobalEvent('system-info-update', data);
```

The Lynx UI side receives it through [`GlobalEventEmitter`](/next/lynxtron/learn/Communication-Between-Node-And-Lynx.md#push-messages-from-nodejs-to-lynx). For a complete example, see [Bidirectional Message Communication Between Node Main Process and Lynx](/next/lynxtron/learn/Communication-Between-Node-And-Lynx.md#bidirectional-message-communication-between-node-main-process-and-lynx).

## Handle Native Modules, Builds, and Packaging

If the Electron project uses Node.js native modules, rebuild them for the Lynxtron runtime:

```bash
npx @lynx-js/lynxtron-rebuild
```

Use [`@lynx-js/lynxtron-builder`](/next/lynxtron/api/@lynx-js/lynxtron-builder/index.md) for app packaging. It is based on `electron-builder` and can continue reading `electron-builder.yml`, but it replaces the Electron runtime with the Lynxtron runtime that matches the current Lynxtron dependency. Start with the [quick start](/next/lynxtron/introduction.md), then migrate your application code. The following scripts match the current scaffold's `lynx.config.ts` and `rsbuild.config.ts`, building the Lynx UI and desktop main process respectively. For an existing project, keep the `build` command that matches its build configuration and replace the packaging entry with `lynxtron-builder`:

```json title="package.json"
{
  "scripts": {
    "build": "rspeedy build --environment lynx && rsbuild build --environment desktop",
    "pack": "npm run build && lynxtron-builder --publish never"
  }
}
```

During migration, check the following:

- Native modules that depend on the Electron ABI are rebuilt with [`@lynx-js/lynxtron-rebuild`](/next/lynxtron/api/@lynx-js/lynxtron-rebuild/index.md).
- Renderer code that directly accessed Node.js has moved into the main process or [preload scripts](/next/lynxtron/learn/Communication-Between-Node-And-Lynx.md#use-preload-scripts).
- `directories.app`, `files`, `extraResources`, and similar options in `electron-builder.yml` point to the Lynxtron main-process output, Lynx bundle, and required resources.
- The Lynx bundle is built correctly and included in the packaged app.
- Frameless windows, transparent windows, drag regions, and system buttons have been rewritten with Lynx UI.

## Recommended Migration Order

1. Create a fresh Lynxtron project and make sure the minimal window and packaging flow work.
2. Move Electron main-process logic such as app lifecycle, menus, tray icons, and dialogs.
3. Replace `BrowserWindow` with `LynxWindow` and load a minimal Lynx bundle.
4. Migrate [preload scripts](/next/lynxtron/learn/Communication-Between-Node-And-Lynx.md#use-preload-scripts) and expose the Node.js capabilities needed by UI through [`NativeModules.nodejs.exposed`](/next/lynxtron/api/@lynx-js/lynxtron/lynx/Interface.LynxtronNodejs.md#exposed).
5. Rewrite Renderer UI window by window, replacing HTML, DOM, and CSS with Lynx elements and styles. If you need a progressive migration path, use `<webview>` first for Web pages that have not been migrated yet.
6. Migrate IPC to `NativeModules.bridge.call` / `NativeModules.bridge.send` and [`LynxWindow.sendGlobalEvent()`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md#sendglobalevent), and listen for [`-lynx-invoke`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md#event--lynx-invoke) / [`-lynx-message`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md#event--lynx-message) events on the main-process side.
7. Rebuild native modules, then use [`@lynx-js/lynxtron-builder`](/next/lynxtron/api/@lynx-js/lynxtron-builder/index.md) to verify packaged assets and platform-specific behavior.

## Continue Reading

- [What is Lynxtron?](/next/lynxtron/learn/what-is-lynxtron.md)
- [Node.js and Lynx Communication](/next/lynxtron/learn/Communication-Between-Node-And-Lynx.md)
- [Building a Custom Window](/next/lynxtron/learn/Custom-Window-Styles.md)
- [Node.js Native Modules](/next/lynxtron/Native-Libraries/NodeJS-Native-Modules.md)
- [Lynx Native Libraries](/next/lynxtron/Native-Libraries/Lynx-Native-Libraries.md)
