# Get Started

Getting your first Positron application up and running takes just a few minutes. Because Positron decouples the JavaScript runtime from the native layout shell, there are no heavy native assets to configure manually during your initial setup.

{% stepper %}
{% step %}

### Installation

Install the core framework directly into your Node.js project using your preferred package manager:

```bash
npm install positron.js
```

#### System Prerequisites

Before booting your application, ensure your development machine has the required compiler tools installed so Positron can stitch together its background dev binaries:

* **macOS:** Xcode Command Line Tools (`swiftc` must be accessible via your terminal).
* **Windows:** .NET SDK (CLI tools capable of executing `dotnet publish` must be configured in your environment system path).
  {% endstep %}

{% step %}

### Write a Basic App

Create an `index.js` file at the root of your project directory. This script acts as your application's **Main Process**, controlling windows, orchestration logic, and backend API routing.

```javascript
const { Window, ipc } = require('positron.js');
const path = require('path');

// 1. Bind asynchronous IPC listeners to handle frontend requests
ipc.handle('get-app-version', (payload, { reply, windowId }) => {
  console.log(`[IPC] Window ${windowId} requested application version details.`);
  
  // Send a safe, serialized JSON response back to the renderer channel
  reply({ version: '1.0.0-alpha' });
});

// 2. Spawn a native OS window container instance
const mainWindow = new Window({
  width: 1024,
  height: 768
});

// 3. Orchestrate your window content once the native shell is fully ready
mainWindow.on('ready', async () => {
  console.log('[Positron] Native window bridge successfully initialized.');
  
  // Resolve an absolute path to your local UI source assets
  const entryPoint = path.join(__dirname, 'public', 'index.html');
  
  mainWindow.loadFile(entryPoint);
  mainWindow.setTitle('My First Positron App');
});
```

{% endstep %}

{% step %}

### Running Your App

Execute your main script entry point:

{% tabs %}
{% tab title="Run" %}
{% code lineNumbers="true" %}

```bash
npx positron run
```

{% endcode %}
{% endtab %}

{% tab title="Build and Run" %}

```shellscript
npx positron dev
```

{% endtab %}

{% tab title="Node" %}

<pre class="language-bash"><code class="lang-bash"><strong>node index.js
</strong></code></pre>

{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}

<details>

<summary>What Happens Under the Hood on First Run?</summary>

1. **Binary Detection:** Positron checks your local project workspace for a compiled `bin/positron-runtime` application file.
2. **Automatic Background Build:** If it's your first time running the project (or if the binary is missing), Positron's core build engine steps in, scans your system paths for native compilers (`swiftc` or `dotnet`), maps any localized extensions, and compiles a slim native platform wrapper on the fly.
3. **IPC Handshake:** The native wrapper process boots up, loads an isolated native viewport container (`WebKit` or `.NET WebView2`), connects securely to the internal Node.js WebSocket engine via port `9000`, and fires the `'ready'` lifecycle event.

</details>


---

# 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/get-started.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.