For AI agents: the complete documentation index is available at /next/llms.txt, the full documentation bundle is available at /next/llms-full.txt, and this page is available as Markdown at /next/lynxtron/learn/what-is-lynxtron.md.
Lynxtron logo
Lynxtron
  • English

      • What is Lynxtron?

      Lynxtron is a framework for building desktop applications with Lynx and Node.js. If you know Electron, you can think of Lynxtron as Electron with the Chromium rendering layer replaced by Lynx.

      • The Main Process side is essentially Electron. Node.js controls the app lifecycle, windows, menus, tray, dialogs, and other OS-level APIs.
      • The UI side is the Lynx runtime. You can use Lynx runtime DSLs such as ReactLynx and VueLynx to build UI, and it ultimately renders native elements such as <view>, <text>, and <image>, not HTML.
      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:

      ElectronLynxtronDifference
      BrowserWindowLynxWindowLoads a Lynx bundle instead of HTML; window construction and customization options such as width, height, frame, transparent, titleBarStyle, and vibrancy work the same way
      app / Menu / Tray / Notification / dialog / shell / screen and other desktop APIsapp / Menu / Tray / Notification / dialog / shell / screen and other desktop APIsMostly follows the Electron API
      contextBridgecontextBridgeexposeInLynxBTS() replaces Electron exposeInMainWorld() 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@lynx-js/lynxtron-rebuildDifferent runtime ABI
      electron-builder@lynx-js/lynxtron-builderLynxtron 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 ConceptHow it is used in LynxtronLearn more
      Elements (<view>, <text>, <image>)Window content uses Lynx elements, not HTMLLynx Elements
      Styling (CSS subset + -x- extensions)Standard Lynx stylingLynx Styling
      ReactLynx / VueLynx and other runtime DSLsWrite UI with DSLs supported by LynxReactLynx / VueLynx
      NativeModulesLynx native module entry point; includes NativeModules.bridge / NativeModules.nodejs channels in LynxtronLynx NativeModules
      GlobalEventEmitterReceives events pushed from the main processLynx 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
      Lynxtron ThreadThread RelationshipElectron CounterpartPrimary Responsibilities
      Main ThreadOne per appElectron Main Process + main-thread responsibilities from Chromium's rendererNode.js main-process APIs, window management, native capabilities, Lynx MTS, input, layout, rendering
      Lynx Background ThreadShared or independent per windowPage business JS in the Electron RendererRuns 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.

      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:

      -> Learn more: Building a Custom Window

      Inter-Thread Communication

      Lynxtron has three inter-thread communication patterns, corresponding to Electron IPC:

      DirectionLynxtronElectron equivalent
      Node.js -> LynxLynxWindow.sendGlobalEvent()webContents.send()
      Lynx -> Node.js (two-way)NativeModules.bridge.call -> -lynx-invoke eventipcRenderer.invoke() + ipcMain.handle()
      Lynx -> Node.js (one-way)NativeModules.bridge.send -> -lynx-message eventipcRenderer.send() + ipcMain.on()

      -> Learn more: Communication Between Node and Lynx

      Node.js Integration via Preload Scripts

      Preload scripts can be understood as an enhancement of Electron preload scripts / 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() 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 on LynxWindow to specify the preload script.
      2. The preload script uses Node.js APIs directly and exposes allowlisted capabilities through contextBridge.exposeInLynxBTS().
      3. Lynx BTS calls the exposed objects through NativeModules.nodejs.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 Steps

      Except as otherwise noted, this work is licensed under a Creative Commons Attribution 4.0 International License, and code samples are licensed under the Apache License 2.0.