# Create

You can extend Positron's core runtime shell by writing platform-native modules in **Swift (macOS)** and **C# (Windows)**. By packing these behaviors into a standard Node dependency, you can seamlessly bridge low-level operating system APIs right into your application's JavaScript lifecycle.

### Extension Manifest Configuration (`package.json`)

To turn an ordinary npm package into a recognized Positron Native Extension, include a custom `positron` property block in its metadata file. This schema instructs Positron's native compilation engine how to register your code interfaces and map your native source assets during compile phases.

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

#### Schema Properties:

* `className`: The naming signature of the primary native object class containing your execution entry point logic.
* `command`: The string identifier keyword utilized on your JavaScript backend (`mainWindow.sendCommand()`) to route frames directly into this plugin module.
* `platforms`: Exact relative file path indicators pointing to the specific platform source code components to be dynamically compiled.

### Implementing the macOS Variant (`Plugin.swift`)

On macOS, your extension class exposes a static `handle` function matching Positron's Swift signature contract. This allows your plugin to work directly with native frameworks like Cocoa and WebKit.

Create the source file path mapping inside your package root (e.g., `src/mac/Plugin.swift`):

{% code lineNumbers="true" %}

```swift
import Cocoa

public class Plugin {
    /// Native interface execution handler called by Positron's runtime bridge
    /// - Parameters:
    ///   - windowId: The targeted unique application viewport layout context index
    ///   - args: An ordered collection of string parameters forwarded from Node.js
    public static func handle(windowId: Int, args: [String]) {
        let alert = NSAlert()
        alert.messageText = args.first ?? "Hello from Positron!"
        alert.alertStyle = .informational
        alert.addButton(withTitle: "OK")
        
        // Execute a native, modal UI system alert dialog
        alert.runModal()
    }
}
```

{% endcode %}

### Implementing the Windows Variant (`Plugin.cs`)

On Windows, your extension must reside within the `PositronWindows` namespace and expose a static `Handle` method matching Positron's C# structural orchestration engine.

Create the source file path mapping inside your package root (e.g., `src/win/Plugin.cs`):

{% code lineNumbers="true" %}

```csharp
using System.Collections.Generic;
using System.Threading.Tasks;
using System.Windows;

namespace PositronWindows
{
    public static class Plugin
    {
        /// Native interface execution handler called by Positron's runtime bridge
        /// - Parameters:
        ///   - windowId: The targeted unique application viewport layout context index
        ///   - args: A generic list of string parameters forwarded from Node.js
        public static void Handle(int windowId: int, List<string> args)
        {
            string message = args.Count > 0 ? args[0] : "Hello from Positron!";
            
            // Marshall the UI presentation logic to clear the primary thread
            Task.Run(() => 
            {
                MessageBox.Show(message, "Notification", MessageBoxButton.OK, MessageBoxImage.Information);
            });
        }
    }
}
```

{% endcode %}

### Install in Project

{% code lineNumbers="true" %}

```bash
npm i <package-path-or-name>
```

{% endcode %}

### Execute

Once you have implemented your code structures, installed it as a dependency, and run `npx positron build` inside your primary application directory, you can invoke your newly added platform behaviors seamlessly from your backend scripts:

{% code lineNumbers="true" %}

```javascript
mainWindow.on('ready', async () => {
    // Triggers the compiled native alert modules across macOS or Windows
    // Arguments: (command_identifier, [...args])
    mainWindow.sendCommand("alert:show", "This is an authentic system notification dialog!");
});
```

{% endcode %}

### Getters

#### C\#

* `App.GetWindow(windowId)`, `App.GetIPCClient(),` `App.GetWebView(windowId)`

#### Swift

* `GetIPCClient(windowId)`, `GetWebView(windowId)`, `GetWindow(windowId)`


---

# 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/create.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.