Native SDK

https://native-sdk.dev/docs
Admin
Native SDK is an open source toolkit for building cross-platform native desktop applications using...
Tokens:220,127
Snippets:1,512
Trust Score:6.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Native SDK CLI and Check Version

Source: https://native-sdk.dev/docs/quick-start

Installs the Native SDK CLI globally and verifies the installation by printing the version. Run this before creating a project with `native init`.

```bash
npm install -g @native-sdk/cli
native version
```

--------------------------------

### Install, build, and package with CEF

Source: https://native-sdk.dev/docs/packaging

Use the same CEF version for install, build, package, and CI verification. This is the usual app-developer flow.

```bash
native cef install --version <pinned-version>
zig build
native package --target macos
```

--------------------------------

### Install panic capture with native_sdk.debug.installPanicCapture

Source: https://native-sdk.dev/docs/debugging

Installs the panic capture during startup. Use after declaring the panic handler. This writes a report to last-panic.txt and appends a fatal trace record.

```zig
native_sdk.debug.installPanicCapture(io, log_setup.paths);
```

--------------------------------

### Install @native-sdk/cli globally

Source: https://native-sdk.dev/docs/packages

Installs the `@native-sdk/cli` package globally, which provides the `native` command and the SDK source. See the Quick Start guide for the full flow.

```bash
npm install -g @native-sdk/cli
```

--------------------------------

### Install the Native SDK discovery skill with npx

Source: https://native-sdk.dev/docs/skills

Run this command once to install the Native SDK discovery skill into your agent's skills directory. The discovery skill is a compact entry point that teaches the agent to load full, version-matched skill content from the installed CLI.

```sh
npx skills add vercel-labs/native
```

--------------------------------

### Install CEF runtime and run native doctor

Source: https://native-sdk.dev/docs/web-engines

Install the prepared CEF runtime and verify the manifest with the doctor command.

```bash
native cef install
native doctor --manifest app.zon
```

--------------------------------

### Package for Linux

Source: https://native-sdk.dev/docs/packaging

Use the native package command to create a Linux install tree with the specified manifest and binary.

```bash
native package --target linux --manifest app.json --binary zig-out/bin/MyApp
```

--------------------------------

### Initialize and start EmbeddedApp with NullPlatform

Source: https://native-sdk.dev/docs/embed

Initializes an EmbeddedApp with a NullPlatform, providing a context, name, and HTML source. After starting, the loaded HTML is available in null_platform.loaded_source.

```zig
var null_platform = native_sdk.NullPlatform.init(.{});
var state: u8 = 0;
var embedded = native_sdk.embed.EmbeddedApp.init(.{
    .context = &state,
    .name = "embedded",
    .source = native_sdk.WebViewSource.html("<p>Embedded</p>"),
}, null_platform.platform());

try embedded.start();
// null_platform.loaded_source now contains the loaded HTML
```

--------------------------------

### Install Native SDK CLI

Source: https://native-sdk.dev

Use the npm package manager to install the Native SDK command-line interface globally.

```bash
$ npm install -g @native-sdk/cli
```

--------------------------------

### native dev command usage

Source: https://native-sdk.dev/docs/cli/dev

Examples of running the native dev command with various flags and configurations.

```bash
native dev
native dev path/to/app -Dweb-engine=chromium
native dev --binary zig-out/bin/MyApp
native dev --binary zig-out/bin/MyApp --url http://127.0.0.1:3000/ --command "npm run dev"
native dev --binary zig-out/bin/MyApp --timeout-ms 60000
```

--------------------------------

### Frontend configuration in app.zon

Source: https://native-sdk.dev/docs/cli/dev

Example configuration block for frontend development settings within the app.zon file.

```zig
.frontend = .{
    .dist = "dist",
    .entry = "index.html",
    .spa_fallback = true,
    .dev = .{
        .url = "http://127.0.0.1:5173/",
        .command = .{ "npm", "run", "dev", "--", "--host", "127.0.0.1" },
        .ready_path = "/",
        .timeout_ms = 30000,
    },
}
```

--------------------------------

### Build and run with zig build run

Source: https://native-sdk.dev/docs/web-engines

Build and run the app, which can also trigger automatic CEF installation when .cef.auto_install is true.

```bash
zig build run
```

--------------------------------

### Initialize and run the Runtime

Source: https://native-sdk.dev/docs/runtime

Configure the Runtime with platform services, security permissions, and window state, then execute the application.

```zig
var runtime = native_sdk.Runtime.init(.{
    .platform = my_platform,
    .trace_sink = fanout.sink(),
    .security = .{
        .permissions = &app_permissions,
        .navigation = .{ .allowed_origins = &.{"zero://app"} },
    },
    .window_state_store = state_store,
    .automation = if (build_options.automation) automation_server else null,
});
try runtime.run(my_app.app());
```

--------------------------------

### Save and load draft with Cmd.store in src/core.ts

Source: https://native-sdk.dev/docs/record-store

Implements a saved-draft workflow in src/core.ts using Cmd.store.get and Cmd.store.set. A get result starts with 1 for a hit and 0 for a miss, with the value following the hit byte. Reissuing the same route key replaces the older in-flight operation, and Cmd.cancel(key) cancels it silently.

```ts
import { Cmd } from "@native-sdk/core";

export interface Model {
  readonly draft: Uint8Array;
  readonly loaded: boolean;
}

export type Msg =
  | { readonly kind: "load" }
  | { readonly kind: "loaded"; readonly result: Uint8Array }
  | { readonly kind: "edited"; readonly draft: Uint8Array }
  | { readonly kind: "saved" }
  | { readonly kind: "store_failed"; readonly reason: Uint8Array };

export const viewUnbound = ["loaded", "saved", "store_failed"] as const;

export function initialModel(): Model {
  return { draft: new Uint8Array(0), loaded: false };
}

export function update(model: Model, msg: Msg): Model | [Model, Cmd<Msg>] {
  switch (msg.kind) {
    case "load":
      return [model, Cmd.store.get("draft/current", {
        key: "load-draft", ok: "loaded", err: "store_failed",
      })];
    case "loaded":
      // A get result starts with 1 for a hit and 0 for a miss. The value
      // follows the hit byte, so an empty value is distinct from absence.
      return msg.result[0] === 1
        ? { draft: msg.result.subarray(1), loaded: true }
        : { ...model, loaded: true };
    case "edited":
      return [{ ...model, draft: msg.draft }, Cmd.store.set(
        "draft/current",
        msg.draft,
        { key: "save-draft", ok: "saved", err: "store_failed" },
      )];
    case "saved":
    case "store_failed":
      return model;
  }
}
```

--------------------------------

### Initialize a native app with a web frontend (native init --frontend next)

Source: https://native-sdk.dev/docs/typescript/packages

Use this command to scaffold a native app with a web frontend, choosing from next, vite, react, svelte, or vue. The scaffold wires the dev-server/bundled-assets split for you.

```bash
native init my_app --frontend next   # or vite | react | svelte | vue
```

--------------------------------

### Initialize and run native project

Source: https://native-sdk.dev

Use these commands to scaffold a new application named my_app and start the development environment to open a real window for live editing of src/app.native.

```bash
$ native init my_app$ cd my_app && native deva real window opens — edit src/app.native while it runs
```

--------------------------------

### Check CEF setup with native doctor

Source: https://native-sdk.dev/docs/debugging/doctor

Runs `native doctor` with a manifest path to check the CEF setup.

```bash
# Check CEF setup
native doctor --manifest app.json
```

--------------------------------

### Initialize a new native app

Source: https://native-sdk.dev/docs/quick-start

Scaffold a new native-rendered application using the native CLI.

```bash
native init my_app
cd my_app
```

--------------------------------

### Run the development server

Source: https://native-sdk.dev/docs/quick-start

Execute the development command to compile the app and SDK, opening a native window with a counter.

```bash
native dev
```

--------------------------------

### Spacer Markup Example

Source: https://native-sdk.dev/docs/components/spacer

An example of using the spacer component within a row to push a button to the far edge of a panel.

```html
<panel width="340" padding="12">
  <row gap="12" cross="center">
    <text>Docs</text>
    <text foreground="text_muted">Source</text>
    <spacer grow="1"></spacer>
    <button size="sm" variant="secondary" on-press="open_changelog">Changelog</button>
  </row>
</panel>
```

--------------------------------

### Initialize a full-control native app

Source: https://native-sdk.dev/docs/quick-start

Scaffold a native application with full control over the build configuration by including a build.zig file.

```bash
native init my_app --full
```

--------------------------------

### Zig: Wire app with native_sdk.UiApp in main

Source: https://native-sdk.dev/docs/app-model

Shows the standard wiring for a native_sdk app in Zig. `create` heap-allocates the app struct and constructs the Model in place; the model starts as `.{}` and boot state is assigned through the returned pointer. The `scene` declares the native window and its GPU surface view.

```zig
const CounterApp = native_sdk.UiApp(Model, Msg);

pub fn main(init: std.process.Init) !void {
    // `create` heap-allocates the multi-MB app struct and constructs the
    // Model in place — neither ever rides the stack.
    const app_state = try CounterApp.create(std.heap.page_allocator, .{
        .name = "my_app",
        .scene = shell_scene,             // one window, one gpu_surface view
        .canvas_label = "main-canvas",    // must match the scene's view label
        .update_fx = update,              // update(model, msg, fx) - or .update for a pure app
        .markup = .{ .source = app_markup, .watch_path = "src/app.native", .io = init.io },
    });
    defer app_state.destroy();
    app_state.model = initialModel();     // boot state: assign through the pointer

    try runner.runWithOptions(app_state.app(), .{ ... }, init);
}
```

--------------------------------

### Create and manage WebViews from JavaScript

Source: https://native-sdk.dev/docs/webviews

JavaScript example showing how to create a WebView, set its frame, navigate, set zoom, set layer, and close it. Coordinates are relative to the parent window; layer controls native stacking.

```javascript
const preview = await window.zero.webviews.create({
  label: "preview",
  url: "https://example.com",
  frame: { x: 24, y: 24, width: 480, height: 320 },
  layer: 10,
  transparent: false,
  bridge: false,
});

await preview.setFrame({ x: 32, y: 32, width: 640, height: 420 });
await preview.navigate("https://example.com/docs");
await preview.setZoom(1.25);
await preview.setLayer(20);
await preview.close();
```

--------------------------------

### Set Chromium engine in app.zon and install CEF

Source: https://native-sdk.dev/docs/web-engines

Configure the app manifest to use the Chromium engine with a manual CEF directory and no auto-install, then install the CEF runtime and build/run the app.

```zig
.web_engine = "chromium",
.cef = .{ .dir = "third_party/cef/<platform>", .auto_install = false },
```

```bash
native cef install
zig build run
```

--------------------------------

### List and get native skills

Source: https://native-sdk.dev/docs/cli

Lists built-in AI agent skills or prints a skill's content. Use `skills get <name>` for a specific skill (e.g., `core` or `native-ui`), `--all` for every non-hidden skill, and `--full` to include reference and template files when present.

```sh
native skills list
native skills get <name> [--full]
native skills get --all [--full]
```

--------------------------------

### Configure build artifacts with root_module

Source: https://native-sdk.dev/docs/zig

Demonstrates how to define an executable in build.zig by creating a root_module with source, target, and optimization settings.

```zig
const exe = b.addExecutable(.{
    .name = "app",
    .root_module = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    }),
});
```

--------------------------------

### Define FileFilter in Zig

Source: https://native-sdk.dev/docs/dialogs

Example of defining a FileFilter array for use in file dialogs.

```zig
const filters = [_]native_sdk.FileFilter{
    .{ .name = "Images", .extensions = &.{ "png", "jpg", "gif" } },
    .{ .name = "All Files", .extensions = &.{ "*" } },
};
```

--------------------------------

### Update archive filename example

Source: https://native-sdk.dev/docs/updates

The expected output filename format for the generated update ZIP.

```text
zig-out/package/my-app-1.1.0-macos-ReleaseFast-update.zip
```

--------------------------------

### Switch Markup

Source: https://native-sdk.dev/docs/components/switch

Example of using the switch component in HTML markup with bindings and disabled states.

```html
<column gap="12">
  <switch checked="{airplane_mode}" on-toggle="toggle_airplane_mode">Airplane mode</switch>
  <switch checked="{notifications}" on-toggle="toggle_notifications">Notifications</switch>
  <switch checked="true" disabled="true">Managed setting</switch>
</column>
```

--------------------------------

### Checkbox Model Update Logic (Zig)

Source: https://native-sdk.dev/docs/components/checkbox

Example of handling the toggle event in a Zig model.

```zig
// model: accepted: bool = false,
.toggle_terms => model.accepted = !model.accepted,
```

--------------------------------

### native build: build ReleaseFast binary

Source: https://native-sdk.dev/docs/cli

Builds a ReleaseFast binary into zig-out/bin/, printing a one-line completion and naming any failing step.

```sh
native build [dir]
```

--------------------------------

### Checkbox Model Update Logic (TypeScript)

Source: https://native-sdk.dev/docs/components/checkbox

Example of handling the toggle event in a TypeScript model.

```ts
// model: { readonly accepted: boolean }
case "toggle_terms":
  return { ...model, accepted: !model.accepted };
```

--------------------------------

### Initialize a Zig-core native app

Source: https://native-sdk.dev/docs/quick-start

Scaffold a native application using a Zig core instead of the default TypeScript core.

```bash
native init my_app --template zig-core
```
Tokens:
Raw