README.md

Native SDK Examples

Most examples here are zero-config apps: app.json or app.zon + src/ (+ assets/) and nothing else. The native CLI owns their build — run any of them straight from its directory:

native dev     # build and run with hot reload
native test    # run the app's test suite
native build   # produce a ReleaseFast binary in zig-out/bin/

(In this repository the CLI is zig-out/bin/native, built by zig build at the root.) A handful of examples own a build.zig because they outgrow the generated graph — each one's build file opens with the reason.

Start here: TypeScript + Native markup

TypeScript is the primary app-authoring language. A new native init my_app project has src/core.ts, src/app.native, and app.json; the core compiles ahead of time to native code, so no JS runtime ships in the app. These examples are the clearest substantial references for that path:

Example	Shows
chatbot	Multi-module TypeScript core, text editing, streaming Cmd.fetch, environment messages, and deterministic replay.
service-feed-reader	The complete services loop: Cmd.fetch, a parsing service reached through the generated @native-sdk/services client, shared record shapes, and recorded replay without the service.
relational-notes	Append-only SQLite migrations, build-time checked SQL, generated typed transactions and page decoders, FTS5, and live queries.
gpu-components	Isolated interactive Native UI specimens, disclosure trees, anchored menus, and controlled component state.
habits	Small habit tracker: stable row keys, streaks, active filtering, chrome geometry, and recorded replay.
kanban	Keyed boards, drag interactions, avatars, controlled scrolling, and file drops.
menu-bar	Status-item lifecycle, native menus, window hiding and reopening, and typed commands.
soundboard	Full music player: audio effects, timers, search, assets, native context menus, and adaptive markup.
typography	Model-derived design tokens, styled paragraphs, alignment, and bundled fonts.
system-monitor	Subprocess effects, timers, parsing, tables, charts, controlled scroll, and confirmation flows.

Soundboard and System Monitor use the canonical unsuffixed folders. Their TypeScript cores and Native markup replace the earlier duplicate Zig implementations. New TypeScript apps need no language suffix.

Earlier native-rendered showcase apps (Zig cores)

Example	Shows
calculator	A complete small app: markup keypad, text-field keyboard path, chrome shortcuts, theming.
notes	Persistence through the effects channel: debounced writes, restore on boot, dialogs, search.
feed	Windowed 100k-row list virtualization with runtime-owned scrolling.
deck	Two model-declared windows and a dense track ledger.
markdown-viewer	Real file I/O through effects, hidden-inset titlebar retrofit, preview + editor.
code-editor	Platform folder picker, bounded filesystem tree, and syntax-highlighted source editor.
gpu-surface	A Metal-backed GPU surface composed beside native controls and WebView content.
gpu-dashboard	Native chrome, a GPU surface, and a retained canvas display list.
canvas-preview	Canvas + WebView in one window, panes snapped to canvas anchors, a status item.
effects-probe	The effect system live: spawn/fetch/file effects, cancellation, worker wakes.

Examples that own their build

Example	Why it keeps a build.zig
hello	Smallest WebView shell, with the SDK module wiring spelled out by hand.
webview	Bridge commands, window APIs, security policy, automation, and optional CEF engine flags.
command-app	One command routed from toolbar, menu, tray, shortcut, and bridge entry points.
capabilities	Guarded OS services: notifications, clipboard, credentials, dialogs, file drops.
native-shell	Native toolbar/sidebar/statusbar chrome around a WebView content area.
native-panels	Split native panels and stacked native controls around WebView content.
browser	Layered WebViews for isolated page content, engine link flags wired by hand.
next, react, svelte, vue	Frontend projects with managed install/build/dev-server steps.
ui-inbox	The builder-view inbox; its -Dmobile lib step feeds the mobile host shims.
mobile-canvas	Builds the mobile embed static library consumed by the iOS/Android canvas shims.

mobile-shell, ios, and android are mobile host projects (Xcode/Gradle shells plus shared app.zon metadata) rather than desktop app directories.

Start with native init for a small TypeScript + Native markup app, then use chatbot, gpu-components, soundboard, or system-monitor according to the feature you need. Use habits for a small TypeScript app, hello for the lower-level WebView path, webview for native commands or WebView policy, capabilities for guarded OS services, and gpu-surface or gpu-dashboard for custom-rendered or retained-canvas panes.