Native SDK: TypeScript and a .native file become one executable

Two source files and one binary

The quick start is a global install and three commands.

npm install -g @native-sdk/cli

which needs Node.js 24 or later, then:

native init my_app
cd my_app
native dev

The generated project opens a counter app, and it contains three files that matter more than the counter does.

`src/core.ts` is the app's model, messages and update function. `src/app.native` is the view, with layout, bindings and message dispatch. And `app.json` holds app identity, windows, permissions and security settings.

Those three files are the architecture in miniature. Logic is TypeScript, interface is markup in a file with its own extension, and the things a native app needs that markup cannot express, permissions and windows, live in a JSON manifest.

So this is not a web view with a native shell. The extension on the view file is the boundary, and it is why the toolkit can claim to compile app logic and views into a native executable.

dev watches markup and rebuilds the core, and --core runs without a window

The development loop is described in enough detail to plan around.

`native dev` watches markup changes and updates the view while preserving app state. TypeScript core changes rebuild and restart the app. So the two halves have different latencies, and that difference is the design: a layout change is hot, a logic change is a restart.

There is also a flag that removes the window from the loop. Use `native dev --core` to exercise core logic under Node.js without opening a window. That is the answer to testing and to CI, where a window is a liability.

The other two commands are `native check` to validate the project and `native build` to create a release binary.

So the tool surface is four verbs, and they cover the loop: dev for the view, dev --core for logic, check for validation, build for the artefact. The README points at the Quick Start documentation for platform prerequisites and the complete workflow rather than repeating them.

Messages, effects, and the boundary between them

The first paragraph of the App Model section is three sentences, and they define where your code is allowed to reach.

Events dispatch typed messages to `update`, which returns the next model and any effects. The view derives its content from the model. Filesystem access, network requests and other external work run through effects and TypeScript services.

So there are three categories: messages come in, effects go out, and the model is the only thing the view reads. A view file cannot fetch, and a core cannot touch the network without declaring an effect.

That constraint is what makes the same core testable under Node.js, because everything the core needs from the outside arrives as an input and leaves as an effect rather than happening as a side effect of running.

The documentation list follows the same division: Native UI for markup, layout and bindings, Components for the built-in component catalog, and TypeScript Services for external work outside the core.

The core is a checked TypeScript subset, and Zig is the alternative

App cores use a checked TypeScript subset and compile to native code.

A subset is a real constraint rather than a word choice. The core compiles to native code, so whatever the subset permits has to be representable natively.

There is a second language for the same job. To write a Zig core instead, create the project with `native init my_app --template zig-core`.

The repository's primary language is Zig, and Zig cores are offered as an alternative from the scaffold.

That also explains a dependency in the README: the CLI uses a compatible Zig toolchain from your `PATH`, or offers to download the pinned version.

Which is the thing to check before you start. If a compatible Zig is already on your PATH, nothing changes about your machine; if it is not, the CLI will fetch a toolchain for you, and you should decide that on purpose rather than discovering it.

Four examples, and the catalog is wider than the README lists

The README names four examples and each one is chosen to show a different mechanism rather than a different colour scheme.

Chatbot, with streaming responses, text editing and TypeScript effects. Soundboard, with audio playback, search, assets and context menus. System monitor, with subprocess effects, tables, charts and timers. And Calculator, with markup, keyboard input and theming.

Between them they cover the four things an embedded app has to do: stream something from a network service, own native media, spawn and watch a process, and accept hardware keyboard input.

The examples directory is much larger than that, and the filenames describe it better than the README does: `accordion-policy/`, `checkable-policy/`, `effect-policy/` and `hold-policy/` are named after the features they exercise rather than after apps, alongside `android/`, `ios/`, `browser/`, `canvas-preview/`, `capabilities/`, `channel-monitor/`, `code-editor/`, `code-workbench/`, `command-app/`, `deck/`, `effects-probe/`, `feed/`, `gpu-components/`, `gpu-dashboard/`, `gpu-surface/` and `hello/`.

A `browser/` example next to native ones is also the clearest signal on optional embedded web content. The example catalog README is where the full list and the authoring language of each app live.

Experimental, with a platform matrix instead of a compatibility claim

Three sentences state the status and they are the first substantive thing after the summary.

Native SDK is experimental. Platform capabilities vary, and mobile support is still evolving. See the platform support matrix for current support.

That is a more useful statement than a version number, because it tells you where the risk is. The risk is not that the toolkit is wrong, it is that what works on one platform does not work on another, and the matrix is where you find out before you design around it.

The tooling acknowledges the same shape. There is a `capabilities/` example in the tree. And the automation documentation is described as inspecting and driving a running app, which is the same idea from the testing side.

The latest release is v0.11.0 on 2026-10-13, after v0.10.1 and v0.10.0 both on 2026-08-24, with the last push on 2026-10-21. A version at 0.11 with two releases on one day in August is a toolkit being changed often, which is consistent with the experimental label.

Documentation is seven pages and the repository carries skills

The documentation list is seven pages, and they divide along the architecture rather than along tasks.

Quick Start covers installation and a first app. Native UI covers markup, layout and bindings. Components is the built-in component catalog. TypeScript Services covers external work outside the core. Then Testing, for headless app tests and runtime integration; Automation, for inspecting and driving a running app; and Packaging, for creating distributable packages.

Testing and Automation being separate pages is the detail worth noticing. One is about asserting behaviour without a window, the other is about the window being there and being driven. For an experimental toolkit that is a deliberate bet on testability.

The repository root says more than the README does. Beyond `build.zig`, `build.zig.zon` and `app.zon`, there is `packages/`, `apps/`, `src/`, `examples/`, `tests/`, `evals/`, `docs/`, `editors/` and `third_party/`. There are also two less usual directories, `skills/` and `skill-data/`, alongside `AGENTS.md`.

So the toolkit carries its own instructions for coding assistants, in version control, next to a CHANGELOG, a CONTRIBUTING file and a RELEASING file.

Editorial conclusion

Native SDK suits someone who wants a real desktop binary with an OS-native window and who is willing to accept that this is experimental, that platform support varies, and that the core is a checked subset of TypeScript rather than all of it. It does not suit you if you need a stable API today or a mobile target, since the README says mobile support is still evolving and points to a platform support matrix. Verify three things before you start: whether your platform is in that matrix, whether your code stays inside the checked TypeScript subset, and that a compatible Zig toolchain is on your PATH, since the CLI will otherwise offer to download a pinned version.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. vercel-labs/native on GitHub