native README

The project's README from github.com/vercel-labs/native. As one markdown file: README.md.

Native SDK

Native SDK is the complete toolkit for building native desktop applications.

Native SDK exists because expressive UI and native performance should not be competing goals. Developers often choose web-based runtimes because they offer freedom, speed and control over the product experience. But that freedom often comes with a heavy runtime. Native SDK keeps the expressive authoring model and replaces the runtime with native rendering.

Views are declarative markup in .native files, logic is plain TypeScript compiled to native code at build time — or Zig, first-class by choice — and Native SDK's own engine draws every pixel into real OS windows. No browser, no WebView, no JS runtime in the binary: Zig is how everything works, TypeScript and Native markup are how apps are authored.

The Soundboard example app rendered by the Native SDK engine: a music library with album cover art, search, and a playback bar
The Notes example app rendered by the Native SDK engine: a three-pane notes manager with folders, a note list, and an open note The Calculator example app rendered by the Native SDK engine: a finished calculation above a full keypad

Soundboard, Notes, and Calculator from examples/ — every pixel drawn by the Native SDK engine, captured through its deterministic reference renderer. The images follow your color scheme.

Quick start

Install the CLI:

npm install -g @native-sdk/cli

Create and run an app:

native init my_app
cd my_app
native dev

A native window opens with a working counter. The whole app is three files of truth — view, logic, manifest — and no build config. The view is src/app.native, a markup file that binds values and dispatches messages (the counter row at its heart):

<row gap="8" main="center" cross="center" grow="1">
  <button variant="secondary" on-press="decrement">-</button>
  <text>{count}</text>
  <button variant="primary" on-press="increment">+</button>
</row>

All logic lives in src/core.ts: a Model interface, a Msg union, and one pure update function — the only place state changes, plain TypeScript compiled to native code at build time:

export function update(model: Model, msg: Msg): Model {
  switch (msg.kind) {
    case "increment":
      return { ...model, count: model.count + 1 };
    case "decrement":
      return { ...model, count: model.count - 1 };
    case "reset":
      return { ...model, count: 0 };
  }
}

Prefer Zig for the core? native init my_app --template zig-core scaffolds the same app with src/main.zig — same loop, same runtime, first-class by choice.

Edit src/app.native while native dev runs and the window updates in place, keeping your state. native dev --core runs the TypeScript core under node for instant logic checks, native check validates the core and every view in milliseconds without building, and native build produces an optimized release binary.

Read the full guide at native-sdk.dev/quick-start.

What you get

Beautiful by default — Great software should not start from a blank slate. The built-in component catalog — buttons, tabs, text fields, dialogs, charts, virtual lists, and more — ships with considered typography, spacing, and color, so the app native init scaffolds already looks intentional the first time its window opens.

Customizable by design — Your app should have its own identity, not ours. Styling is design tokens end to end: color, radius, and typography resolve by name, re-resolve live when the theme changes, and can be replaced wholesale — examples/soundboard and examples/deck are the same music player separated only by tokens and a chrome pass.

Native from the start — Every interface is rendered without a browser or WebView. The engine draws into real OS windows while scroll physics, menus, dialogs, the tray, and text input stay with the operating system, and markup compiles into the executable at build time, so a release build carries no parser or interpreter — the scaffolded counter app builds to a single binary a few megabytes small.

Predictable state — State changes should be explicit, inspectable and easy to reason about. Events produce messages, messages update state, and state renders the interface; markup can bind and dispatch but never mutate. The loop is so deterministic that native automate record journals a session and replay reproduces it headlessly, verified frame by frame against state fingerprints.

Simple authoring — Interfaces should be easy to read, easy to write and easy to generate. Views are elements, flex layout, {bindings}, and expressions like selected="{f == filter}", and native check validates every view against your app's actual Model and Msg — bindings, iterables, message tags — in milliseconds, with file:line:column errors that teach.

AI is part of the workflow — Native SDK is designed for a world where humans and AI agents build software together. Every app embeds an automation server, so any agent can read accessibility snapshots, drive widgets, assert on live state, and take deterministic screenshots of the running window; accessibility findings are machine-checked in native check; and the CLI ships the agent skills that teach all of it (native skills list).

Examples

The apps pictured above live in examples/, most as zero-config projects with a manifest plus src/ and no build files, run straight from their directory with native dev. Many examples predate the current app.json default and retain app.zon; both formats have the same capabilities. Start with the TypeScript examples when learning the primary authoring path. The -ts suffix on soundboard-ts and system-monitor-ts is historical because those apps are ports kept beside older Zig originals. Chatbot is TypeScript-only and follows the unsuffixed naming used by new apps created with native init.

Example What it shows
chatbot TypeScript + Native markup end to end: modules, a text editor, streaming fetch effects, and replay-safe configuration.
soundboard-ts The full music-player showcase in TypeScript + Native markup: audio, search, assets, timers, and context menus.
system-monitor-ts A live process monitor in TypeScript + Native markup: subprocess effects, tables, charts, and timers.
calculator A complete small app: markup keypad, keyboard input, chrome shortcuts, theming.
notes Persistence through the effects channel: debounced writes, restore on boot, dialogs, search.
soundboard Album grid with decoded cover art, context menus, timers, and a custom theme.
deck The soundboard player rebuilt as a dense hardware chassis: two windows, same widgets, different tokens.
feed A 100,000-row list, virtualized with runtime-owned scrolling.

The unsuffixed showcase apps above predate the TypeScript default and retain their Zig cores as first-class alternative implementations. The full catalog in examples/README.md also covers guarded OS capabilities, GPU surfaces, WebView composition, web-frontend shells, and the iOS/Android embed hosts.

Platforms

macOS is the primary development platform and carries the deepest support: Metal presentation, OS scroll physics, native context menus, app menus, tray, and dialogs. Linux runs the full showcase through the deterministic software renderer in real windows, with pointer, keyboard, scroll, native context menus, IME composition, and HiDPI; Windows runs on a Win32 host with native context menus and IME composition and is exercised in CI, including real input injection. Mobile support is experimental: iOS is simulator-proven through the embed library and Android cross-compiles with the full embed ABI, but APIs and tooling on both are still evolving — desktop is the mature surface. WebView surfaces coexist on every desktop platform. The platform support matrix documents exactly what each host supports today.

Documentation

The full documentation is at native-sdk.dev.

Contributing

Native SDK is pre-1.0: APIs still move, and the toolkit is evolving quickly. Bug reports and focused pull requests are welcome — for larger changes, open an issue first so the design can be discussed. See CONTRIBUTING.md for the development setup and local checks.

License

Apache-2.0

native (vercel-labs/native)

Searching Database…

7.8K ·GitHub
Native
Что это такое?Native SDK — это набор инструментов для создания нативных настольных приложений: вы пишете представления на декларативной разметке .native, а логику на обычном TypeScript (или Zig). SDK компилирует всё в нативный код, который его собственный движок выводит прямо в настоящие окна ОС, без браузера, WebView или JS-среды выполнения в итоговом исполняемом файле.
Это UI-фреймворк или больше похоже на игровой движок, который сам рисует окна?Это декларативный UI-фреймворк со своим движком отрисовки: разметка (файлы .native) привязывается к состоянию и передаёт сообщения в цикле model/message/update, а собственный движок рисует каждый пиксель в настоящих окнах ОС, а не передаёт это браузеру или нативному набору виджетов ОС.
Как создать и запустить первое приложение?Установите CLI, затем выполните native init, чтобы создать новое приложение (представление, логика и манифест: три файла, без конфигурации сборки), и native dev, чтобы запустить его в настоящем окне с работающим счётчиком. Изменения в src/app.native во время работы native dev сразу обновляют окно.
Нужно знать Zig или достаточно TypeScript?TypeScript — основной способ написания логики приложения, он компилируется в нативный код на этапе сборки. Zig поддерживается как полноценное альтернативное ядро, если вы предпочитаете его (native init myapp --template zig-core), но он не обязателен.
Можно ли использовать это в продакшене?Нет. Native SDK находится в версии до 1.0, API ещё меняются, так что ждите несовместимых изменений. Поддержка мобильных платформ (iOS/Android) прямо названа экспериментальной, а десктоп описан как зрелая часть.
Можно ли выпустить это на iOS или Android?Мобильная поддержка экспериментальна: работа iOS подтверждена через библиотеку embed в симуляторе, Android кросс-компилируется с полным embed ABI, но API и инструменты для обеих платформ всё ещё развиваются.
Работает ли это на Windows и Linux так же, как на macOS?Нет. Основная платформа — macOS, с самой глубокой поддержкой (вывод через Metal, нативные меню, системный трей, диалоги). Linux запускает полную демонстрацию через детерминированный программный рендерер. Windows работает на хосте Win32 с нативными контекстными меню и IME и регулярно проверяется в CI.
Что встроенный сервер автоматизации позволяет делать ИИ-агентам?Каждое приложение содержит встроенный сервер автоматизации, чтобы агенты могли читать снимки доступности, управлять виджетами, проверять живое состояние и делать детерминированные скриншоты запущенного окна. CLI также поставляет навыки для агентов (native skills list), которые описывают этот рабочий процесс.
Как устроены темы и оформление?Оформление построено на дизайн-токенах сквозным образом: цвет, скругление и типографика определяются по имени, обновляются на лету при смене темы и могут полностью заменяться. Поэтому одно и то же приложение может выглядеть совсем иначе, достаточно поменять токены.
Насколько большое скомпилированное приложение?Разметка компилируется прямо в исполняемый файл на этапе сборки, поэтому релизная сборка не содержит парсера или интерпретатора. Собранный пример со счётчиком превращается в один бинарный файл размером всего в несколько мегабайт.
What are similar projects?mygo, Valdi, ng-native, gpui-kit, kivy, e2e, flutter, fyne
Which topics is it in?zig, ui-framework, webview, gui-framework, declarative, toolkit, metal, state-management, design-system, native, accessibility, component-library
Creator
vercel-labs
Size
45.8 MB
Stars
7.8K
Updated
CommitOct 16Releasev0.11.0Oct 13
Age
5mo
Commits · 90 Days