# 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

#### 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`)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://positronjs.gitbook.io/v1/intro.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.