> For the complete documentation index, see [llms.txt](https://positronjs.gitbook.io/v1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://positronjs.gitbook.io/v1/intro.md).

# Intro

{% hint style="info" %}
Note: these docs will always reflect the **latest version.** If a documented method isn't available, update the framework.
{% endhint %}

Positron is a lightweight, cross-platform hybrid application framework designed to build desktop applications using a native compiled runtime shell (Swift/Cocoa/WebKit on macOS, and C#/.NET on Windows) driven by a Node.js main process. Unlike traditional resource-heavy frameworks, Positron separates the native windowing/render process from the JavaScript application state, establishing a lightweight, dual-process environment unified by a localized WebSocket IPC channel.

### Architecture & Core Components

Positron operates via a split architecture:

1. The Node.js Master Process (index.js): Manages application lifecycles, creates windows, sets native menus, and hosts the IPC WebSocket server.
2. The Native Runtime Process: A platform-specific, pre-compiled native binary (positron-runtime) responsible for rendering web views and implementing host OS features.
3. IPC Router (ipc.js): A unified, asynchronous routing layer that handles bidirectional events between your web app render layers and your backend.

```mermaid
graph TD
    Master["<b>NODE.JS MASTER PROCESS</b><br>(index.js)<br><hr>• Manages App Lifecycle<br>• Window Creation Orchestration<br>• Native Menu Config Management"]
    
    Runtime["<b>NATIVE RUNTIME PROCESS</b><br>(positron-runtime)<br><hr>• Platform-Specific OS Features<br>• Renders UI Views (WebKit/VW2)<br>• Hosts Client-Side App Assets"]
    
    Router["<b>IPC ROUTER (ipc.js)</b><br><hr>• Hosts localized WebSocket Server<br>• Handles bidirectional event routing via JSON frames"]


    Master --> Router
    Runtime --> Router

    classDef box fill:#333,stroke:#333,stroke-width:1px,text-align:left;
    class Master,Runtime,Router box;
```

### Features

#### Native Framework Integration

* Drops specialized heavy chromium embeddings in favor of native UI viewports&#x20;
  * WebKit on macOS
  * .NET Webview2 on Windows
  * GTK+ 3 and WebKit2GTK on Linux

#### Stitched Native Extensions

* Seamlessly hooks developer-created third-party plugins directly into the native build registry at compile time.

#### Production Packager

* Automatically abstracts bundle constraints to output native macOS .app structures (complete with mandatory Info.plist manifests) and clean Windows application folders.

#### Zero-Config Dev Builds

* Automatically detects missing platform-specific native binaries on launch and compiles them in the background.

### Prerequisites

* Node.js (v16+)
* macOS: Xcode Command Line Tools (swiftc)
* Windows: .NET SDK (CLI tools capable of executing `dotnet publish`)
* C++ compiler (G++ is the default), GTK+ 3 and WebKit2GTK on Linux
  * Docker if building for Linux on macOS or Windows
  * More info: [Linux](https://positronjs.gitbook.io/v1/cli/package/linux.md)
