Native

The Native target compiles your Primate application into standalone desktop executables for Windows, macOS, and Linux. It embeds your app and uses a system WebView to render the UI.

Under the hood, Primate runs an HTTP server inside the executable and points the WebView at it, so you ship a single desktop app without needing a separate web server.

Setup

Install the native module:

npm install @primate/native

Platform prerequisites

Linux x64 uses the WebKitGTK 6.0 sidecar from @rcompat/webview. Running a native app locally, in CI, or in a container requires GTK 4, WebKitGTK 6.0, and libsoup 3 from the host distribution:

# Arch Linux
sudo pacman -S webkitgtk-6.0

# Debian and Ubuntu
sudo apt install libgtk-4-1 libwebkitgtk-6.0-4

# Fedora
sudo dnf install gtk4 webkitgtk6.0

For a Debian or Ubuntu container, install libgtk-4-1 and libwebkitgtk-6.0-4 in the image before launching the executable. Building or cross-compiling alone does not load these libraries, but a launch smoke test does.

GTK 3, WebKitGTK 4.0, and libsoup 2 are not ABI-compatible substitutes. Do not work around a missing library with a compatibility symlink.

macOS uses the system WebKit framework. Windows uses the system WebView2 runtime; the Linux packages above are not required on either platform.

Configure your application:

// config/app.ts
import config from "primate/config";
import native from "@primate/native";

export default config({
  modules: [native()],
});

How it works

Primate compiles a launcher into the executable: the parent process serves your built app and a child process owns the WebView window, whose event loop must run on the process main thread (a requirement of macOS AppKit). Navigation, cookies, and fetch requests work as they do in the browser.

The build embeds your bundled server into the executable -- routes, middleware, modules, client bundles, and static files alike -- so the compiled app runs on its own, without the build directory it was produced in. The launcher bakes the start URL into the executable at build time from your http config, with 0.0.0.0 and empty hosts rewritten to 127.0.0.1 (WebKit refuses those spellings). At launch, an explicitly set PORT environment variable wins and the window navigates the resulting URL; otherwise the server is pinned to the baked-in port, so the compiled app always serves and navigates the same URL. The child probes the server on both localhost and 127.0.0.1 spellings before navigating. If the server never becomes reachable, or the webview fails to load, the executable exits with a nonzero code instead of starting a broken window.

• Server: serves your built app; you can still use routes, middleware, and modules.
• WebView: renders your UI using the system WebView for each platform.

Platform Support

Currently supported platforms:

Building

Development

Run the dev loop with a Webview window attached to the watch server:

bunx --bun primate dev --target=desktop

No binary is compiled: the window is an uncompiled script navigating the watch server, and on every file change, primate rebuilds the server bundle and reloads the page in the window. Close the window to leave the dev loop, and Ctrl-C it to stop the server. Window requests appear in the terminal prefixed with [native].

Production

Build a native executable for the host platform:

bunx --bun primate build --target desktop

This will create an executable app (or app.exe on Windows) inside build. The embedded server makes the executable self-contained: copying it out of build and running it is enough to launch the app.

Cross-compilation

You can target specific platforms from your development machine:

{
  "scripts": {
    "build:linux-x64": "bunx --bun primate build --target linux-x64",
    "build:darwin-x64": "bunx --bun primate build --target darwin-x64",
    "build:darwin-arm64": "bunx --bun primate build --target darwin-arm64",
    "build:windows-x64": "bunx --bun primate build --target windows-x64"
  }
}

Run, for example:

bunx --bun primate build --target windows-x64

Build Output

build/
└── app              # Linux/MacOS/Windows executable (app.exe on Windows)

The executable embeds your bundled server and all client and static assets: it is the only thing you need to copy when distributing the app, plus any sidecar directories modules have declared (see Sidecars below).

Configuration

Example

import native from "@primate/native";

export default config({
  modules: [
    native({
      // start URL when app launches
      start: "/",

      // enable debug mode
      debug: false,

      // window size
      width: 1280,
      height: 720,
    }),
  ],
});

Sidecars

Modules of a Primate app can contribute runtime files that a compiled app needs next to its executable. A module declares these files as sidecars through Primate's build contract; the Native module copies each declared file into the build directory, with its declared relative path preserved -- so the compiled app resolves it from its own directory at launch.

Sidecars are declared by the module that owns the runtime in question; Native itself has no knowledge of which modules or runtimes an app was built with. Apps without declarations build executables without sidecars. The most common use is the Pyodide runtime of @primate/python apps; see the Python documentation for details.

Sidecar files are validated at declaration: destinations have to be portable relative paths inside the build output, and a declared file that is missing or uncopyable fails the build instead of shipping a broken distribution.

Distribution

The built executable is the distributable: it embeds the bundled server and all client and static assets, so it runs from any location you copy it to. Sidecar directories modules declared (see Sidecars above) ship alongside it; the most common is the Pyodide runtime directory of @primate/python apps. Shipping native apps usually involves platform packaging and signing:

• Windows: package/sign your app.exe and its sidecar files as needed for distribution.
• macOS: wrap the executable and its sidecar files into an .app bundle, then notarize/sign.
• Linux: distribute the binary and its sidecar files directly or via a package format of choice, and declare GTK 4, WebKitGTK 6.0, and libsoup 3 as host dependencies.

These steps depend on your release tooling; integrate them after primate build completes.