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

# What is Lynxtron?

Lynxtron is a framework for building desktop applications with [Lynx](https://lynxjs.org/) and Node.js. If you know [Electron](https://www.electronjs.org/), you can think of Lynxtron as **Electron with the Chromium rendering layer replaced by Lynx**.

- The **Main Process** side is essentially [Electron](https://www.electronjs.org/docs/latest/tutorial/process-model#the-main-process). Node.js controls the app lifecycle, windows, menus, tray, dialogs, and other OS-level APIs.
- The **UI** side is the [Lynx](https://lynxjs.org/guide/start/quick-start.html) runtime. You can use Lynx runtime DSLs such as ReactLynx and VueLynx to build UI, and it ultimately renders native 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), not HTML.

:::tip Already familiar with Electron and Lynx?
Then you already know most of Lynxtron. This page covers the parts that only exist because Electron and Lynx are combined.
:::

## What Comes from Electron

The main process runs on Node.js; Lynxtron provides Electron-style desktop APIs such as windows, app lifecycle, menus, and tray. If you have used Electron, these common concepts are mostly the same:

| Electron                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Lynxtron                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Difference                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`BrowserWindow`](https://www.electronjs.org/docs/latest/api/browser-window)                                                                                                                                                                                                                                                                                                                                                                                                     | [`LynxWindow`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md)                                                                                                                                                                                                                                                                                                                                                                                                                                          | Loads a Lynx bundle instead of HTML; window construction and customization 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 [`vibrancy`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxWindowConstructorOptions.md#vibrancy) work the same way |
| [`app`](https://www.electronjs.org/docs/latest/api/app) / [`Menu`](https://www.electronjs.org/docs/latest/api/menu) / [`Tray`](https://www.electronjs.org/docs/latest/api/tray) / [`Notification`](https://www.electronjs.org/docs/latest/api/notification) / [`dialog`](https://www.electronjs.org/docs/latest/api/dialog) / [`shell`](https://www.electronjs.org/docs/latest/api/shell) / [`screen`](https://www.electronjs.org/docs/latest/api/screen) and other desktop APIs | [`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) / [`screen`](/next/lynxtron/api/@lynx-js/lynxtron/Variable.screen.md) and other desktop APIs | Mostly follows the Electron API                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [`contextBridge`](https://www.electronjs.org/docs/latest/api/context-bridge)                                                                                                                                                                                                                                                                                                                                                                                                     | [`contextBridge`](/next/lynxtron/api/@lynx-js/lynxtron/context-bridge/Interface.ContextBridge.md)                                                                                                                                                                                                                                                                                                                                                                                                                 | [`exposeInLynxBTS()`](/next/lynxtron/api/@lynx-js/lynxtron/context-bridge/Interface.ContextBridge.md#exposeinlynxbts) replaces Electron [`exposeInMainWorld()`](https://www.electronjs.org/docs/latest/api/context-bridge) in Lynxtron and adds the ability to expose callable JS objects from Node.js to Lynx; exposed objects can contain functions, closures, and asynchronous APIs that return Promises                                                                                                                                                                                                                                                                                                                                               |
| [`@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)                                                                                                                                                                                                                                                                                                                                                                                                                              | Different runtime ABI                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [`electron-builder`](https://www.electron.build/)                                                                                                                                                                                                                                                                                                                                                                                                                                | [`@lynx-js/lynxtron-builder`](/next/lynxtron/api/@lynx-js/lynxtron-builder/index.md)                                                                                                                                                                                                                                                                                                                                                                                                                              | Lynxtron packaging entry based on electron-builder; reuses `electron-builder.yml`, replaces the Electron runtime with the matching Lynxtron runtime, and supports macOS universal builds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

## What Comes from Lynx

The UI layer is standard Lynx. You can use runtime DSLs supported by Lynx, such as ReactLynx and VueLynx, to build UI:

| Lynx Concept                                                                                                                                                                                                           | How it is used in Lynxtron                                                                                                                                                             | Learn more                                                                                                |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| [Elements](https://lynxjs.org/guide/ui/elements-components.html) ([`<view>`](/next/api/elements/built-in/view.md), [`<text>`](/next/api/elements/built-in/text.md), [`<image>`](/next/api/elements/built-in/image.md)) | Window content uses Lynx elements, not HTML                                                                                                                                            | [Lynx Elements](https://lynxjs.org/guide/ui/elements-components.html)                                     |
| [Styling](https://lynxjs.org/guide/ui/styling.html) (CSS subset + `-x-` extensions)                                                                                                                                    | Standard Lynx styling                                                                                                                                                                  | [Lynx Styling](https://lynxjs.org/guide/ui/styling.html)                                                  |
| ReactLynx / VueLynx and other runtime DSLs                                                                                                                                                                             | Write UI with DSLs supported by Lynx                                                                                                                                                   | [ReactLynx](https://lynxjs.org/react/introduction.html) / [VueLynx](https://vue.lynxjs.org/)              |
| [`NativeModules`](https://lynxjs.org/guide/use-native-modules)                                                                                                                                                         | Lynx native module entry point; includes `NativeModules.bridge` / [`NativeModules.nodejs`](/next/lynxtron/api/@lynx-js/lynxtron/lynx/Interface.LynxtronNodejs.md) channels in Lynxtron | [Lynx NativeModules](https://lynxjs.org/guide/use-native-modules)                                         |
| [`GlobalEventEmitter`](/next/guide/interaction/event-handling/event-propagation.md#globaleventemitter)                                                                                                                 | Receives events pushed from the main process                                                                                                                                           | [Lynx GlobalEventEmitter](/next/guide/interaction/event-handling/event-propagation.md#globaleventemitter) |

## Architecture: Single Process, Two Isolated Threads

Unlike Electron's multi-process model (Main Process + Renderer Process), Lynxtron runs in a **single process** and uses **Main Thread + Lynx Background Thread** as a thread-level dual of Electron's two-process model. The Lynx Background Thread can be shared by multiple windows, or windows can use independent background threads.

![Lynxtron single-process two-thread architecture](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/lynxtron/lynxtron-architecture-en.png)
| Lynxtron Thread            | Thread Relationship              | Electron Counterpart                                                          | Primary Responsibilities                                                                                                                                                                                                       |
| -------------------------- | -------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Main Thread**            | One per app                      | Electron Main Process + main-thread responsibilities from Chromium's renderer | Node.js main-process APIs, window management, native capabilities, Lynx [MTS](/next/react/main-thread-script.md), input, layout, rendering                                                                                     |
| **Lynx Background Thread** | Shared or independent per window | Page business JS in the Electron Renderer                                     | Runs directly on Node.js, hosts isolated BTS Contexts for windows, and executes Lynx UI business logic; BTS Context is not the Node.js global environment and can access only allowlisted Node.js capabilities through bridges |

In a single process, Lynxtron puts the control plane and Lynx main-thread capabilities on the main thread, and puts Lynx UI business logic on the Lynx Background Thread. The Lynx Background Thread runs directly on Node.js, but each window's BTS Context is an isolated context, not the Node.js global environment, so it cannot directly use Node.js APIs. Multiple windows can share one background thread, or windows can be assigned independent background threads; either way, their BTS Contexts remain isolated. BTS can access Node.js only through `NativeModules.bridge` or allowlisted [preload scripts](/next/lynxtron/learn/Communication-Between-Node-And-Lynx.md#use-preload-scripts).

## Key Differences in Lynxtron

The following mechanisms connect the Electron-like main process model with the Lynx UI runtime, and are the parts that need extra attention compared with Electron or pure Lynx:

### Desktop UI with Lynx Elements

Lynxtron adds desktop-specific capabilities to Lynx's UI system:

- **[`LynxWindow`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md) replaces Electron [`BrowserWindow`](https://www.electronjs.org/docs/latest/api/browser-window)**: the window loads a Lynx bundle and renders UI with Lynx elements instead of loading an HTML page
- **[`-x-app-region: drag`](/next/lynxtron/learn/Custom-Window-Styles.md#define-ui-draggable-regions)**: make a Lynx element act as a window drag handle, similar to Electron's [`-webkit-app-region: drag`](https://www.electronjs.org/docs/latest/tutorial/custom-window-interactions)
- **[`<title-bar-view>`](/next/api/elements/built-in/title-bar-view.md)**: a built-in Lynx element for custom title bars

-> [Learn more: Building a Custom Window](/next/lynxtron/learn/Custom-Window-Styles.md)

### Inter-Thread Communication

Lynxtron has three inter-thread communication patterns, corresponding to [Electron IPC](https://www.electronjs.org/docs/latest/tutorial/ipc):

| Direction                     | Lynxtron                                                                                                                             | Electron equivalent                                                                                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Node.js -> Lynx**           | [`LynxWindow.sendGlobalEvent()`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md#sendglobalevent)                           | [`webContents.send()`](https://www.electronjs.org/docs/latest/api/web-contents)                                                                               |
| **Lynx -> Node.js** (two-way) | `NativeModules.bridge.call` -> [`-lynx-invoke`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md#event--lynx-invoke) event   | [`ipcRenderer.invoke()`](https://www.electronjs.org/docs/latest/api/ipc-renderer) + [`ipcMain.handle()`](https://www.electronjs.org/docs/latest/api/ipc-main) |
| **Lynx -> Node.js** (one-way) | `NativeModules.bridge.send` -> [`-lynx-message`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md#event--lynx-message) event | [`ipcRenderer.send()`](https://www.electronjs.org/docs/latest/api/ipc-renderer) + [`ipcMain.on()`](https://www.electronjs.org/docs/latest/api/ipc-main)       |

-> [Learn more: Communication Between Node and Lynx](/next/lynxtron/learn/Communication-Between-Node-And-Lynx.md)

### Node.js Integration via [Preload Scripts](/next/lynxtron/learn/Communication-Between-Node-And-Lynx.md#use-preload-scripts)

[Preload scripts](/next/lynxtron/learn/Communication-Between-Node-And-Lynx.md#use-preload-scripts) can be understood as an enhancement of [Electron preload scripts](https://www.electronjs.org/docs/latest/tutorial/tutorial-preload) / contextBridge model for Lynx BTS. A preload script runs in an isolated context with Node.js capabilities, then exposes explicitly allowed methods or objects to Lynx UI.

Unlike Electron, Lynxtron's preload scripts and BTS are isolated JS contexts in the same process. [`contextBridge.exposeInLynxBTS()`](/next/lynxtron/api/@lynx-js/lynxtron/context-bridge/Interface.ContextBridge.md#exposeinlynxbts) does not expose only serializable message payloads. It exposes JS objects that BTS can call directly; those objects can contain functions, closures, and can return Promises.

The core flow is:

1. Configure [`lynxPreference.preload`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxPreference.md#preload) on [`LynxWindow`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md) to specify the preload script.
2. The preload script uses Node.js APIs directly and exposes allowlisted capabilities through [`contextBridge.exposeInLynxBTS()`](/next/lynxtron/api/@lynx-js/lynxtron/context-bridge/Interface.ContextBridge.md#exposeinlynxbts).
3. Lynx BTS calls the exposed objects through [`NativeModules.nodejs.exposed`](/next/lynxtron/api/@lynx-js/lynxtron/lynx/Interface.LynxtronNodejs.md#exposed).

The Lynx Background Thread that hosts BTS runs directly on Node.js, but BTS is still in an isolated context. It is not the Node.js global environment and cannot directly access Node.js APIs. All Node.js capabilities must be explicitly exposed through preload scripts.

-> [Learn more: Node.js and Lynx Communication in Lynxtron](/next/lynxtron/learn/Communication-Between-Node-And-Lynx.md)

## Next Steps

- **Ready to code?** -> [Quick Start](/next/lynxtron/introduction.md)
- **Learn by building** -> [Tutorial: Build Your Own Browser](/next/lynxtron/learn/introduction_to_browser.md)
- **API Reference** -> [@lynx-js/lynxtron API](/next/lynxtron/api/@lynx-js/lynxtron/index.md)
