# Setup

Positron features a modular plugin architecture that allows JavaScript applications to hook directly into low-level host operating system layers. By registering a native extension, you can execute compiled Swift or C# code on the host machine right from your Node.js backend using custom command frames.

### Installing a Native Extension

To add a third-party extension or plugin to your workflow, install it directly into your project's node dependencies:

```bash
npm install <extension-package-name>
```

#### How Extensions Declare Themselves

Positron identifies a valid native plugin by reading a dedicated `positron` configuration schema block inside the extension's `package.json`:

```json
{
  "name": "positron-toast-plugin",
  "version": "1.0.0",
  "positron": {
    "className": "ToastPlugin",
    "command": "toast:show",
    "platforms": {
      "darwin": "src/mac/ToastPlugin.swift",
      "win32": "src/win/ToastPlugin.cs"
    }
  }
}
```

* Positron automatically scans your project's `dependencies` tree looking for this configuration metadata whenever a native compilation is triggered.

### Compile the Native Binary

While development mode automatically triggers a clean background build if your native binary wrapper is missing, you will want to force an explicit compile phase when integrating new native dependencies to stitch their modules into the core framework layout.

Run the native compilation command via the CLI:

```bash
npx positron build
```

<details>

<summary>What Happens During the Build?</summary>

1. **Dependency Mapping:** `builder.js` discovers all installed local dependencies declaring a `positron` block.
2. **Code Stitching:** The build engine automatically generates platform-native code registries (`Registry.swift` on macOS or `Registry.cs` on Windows).
3. **Platform Compiling:** The script binds the extension files (`.swift` or `.cs`) directly into the final executable layout, outputting a high-fidelity binary matching your app configuration within the `bin/` directory.

</details>

<details>

<summary>Command Registry Layout</summary>

When you call `sendCommand("toast:show", ["Hello..."])`, the event frame bypasses standard web view rendering engine components entirely. The framework's core application runner routes the identifier string directly through the auto-generated native mapping table built during step 2:

* **On macOS (Registry.swift):**`Registry.swift` Maps the string to your Swift controller signature: `["toast:show"]: ToastPlugin.handle`.
* **On Windows (Registry.cs):**`Registry.cs` Maps the string to your C# action delegate lookup entry: `{ "toast:show", ToastPlugin.Handle }`.

</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/extensions/setup.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.