Native Shell (NSH)

Build once, native everywhere. Native Shell is a native UI framework for iOS, Android, macOS, Windows, Linux and the web, built in Rust. It unifies components, state, logic and API, with app-owned visual design and platform rendering: native views on iOS, Android, macOS, Windows and Linux, HTML on the web, GPUI in GPUI apps, with the platform's own text, input and interaction (a menu is a popup on the desktop and a sheet on a phone). Write the whole app in Rust, its screens in TSX, or combine both with shared Rust components.

Package it as a standalone app on every platform, or embed it in an existing one. On the same engine, apps load TSX modules at run time — plugins, features, UI generated by AI — delivered as signed packages and run in a sandbox the host configures.

Documentation, guides and live demos: nsh.dev.

Goals

Native views and interaction, with an app-owned design: NSH shares components, state and APIs across platforms, while the app controls colors, typography, spacing, shapes and motion. nsh/base provides the behavior and accessible structure of common controls such as Button, Checkbox and Switch; apps and community libraries give them a look. Platform modules expose capabilities specific to their platforms, such as the mobile system tab bar.

Read Goals and design principles for the component boundaries and how these goals guide Rust apps, TSX modules and AI-generated UI.

Features

• Write apps in Rust, TSX, or both, and render with each platform's own UI, sharing the same reactive engine, flexbox and grid layout, system text, input and accessibility.
• Give your app its own look: NSH provides the primitives, Tailwind classes, a theme and an unstyled UI foundation (nsh/base: navigation, safe areas, dialogs, the keyboard, the status bar), and your app draws its components from them in TSX or Rust.
• Embed in existing native apps alongside components such as maps and web views, or package as standalone apps and static websites.
• Deliver TSX screens at run time with signed packages and host-controlled sandbox capabilities.
• Build AI-generated screens with TSX and Tailwind, generated TypeScript declarations and model-readable documentation.
• Iterate with TSX hot updates, headless tracing and a single Rust-built nsh CLI for building and packaging.

Platforms

Platform	Drawn with	Embed with	Requires
iOS	UIKit, CoreText	NshAppView (Swift, NativeShell.xcframework)	iOS 15+
Android	Android views, StaticLayout	NshView (Java / Kotlin, nsh.aar)	Android 9 (API 28)+
macOS	AppKit, Core Animation, CoreText	AppView (Rust, nsh-platform-macos)	macOS 14+
Windows	Win32, Direct2D, DirectWrite	AppView (Rust, nsh-platform-windows)	Windows 10 1809+
Linux	GTK 4, Pango	AppView (Rust, nsh-platform-linux)	GTK 4.14+
GPUI (macOS, Windows, Linux)	GPUI (GPUI Fast)	AppView (Rust, a GPUI view, nsh-platform-gpui)	macOS, Windows; Linux with Vulkan
Web	HTML, CSS	createPlayer (JavaScript) or an iframe	Modern browsers

Each desktop runs and packages apps with its own backend (AppKit, Win32, GTK 4). The GPUI backend draws with GPUI on all three desktops and embeds NSH in GPUI and GPUI Kit apps; nsh run --target gpui shows an app as they do. The web platform (nsh run --target web, nsh package --target web) publishes apps as static sites and runs the website's live demos.

Quick start

Install the nsh command (other ways):

curl -fsSL https://nsh.dev/install.sh | sh

Build and install the latest main from source (Git, Rust and the platform build dependencies required):

curl -fsSL https://nsh.dev/install.sh | sh -s -- --source
nsh -V # nsh 0.1.1 (abcdef0)

Re-run to update. The checkout stays in ~/.nsh/source for runtime builds.

brew install longbridge/tap/nsh

irm https://nsh.dev/install.ps1 | iex

Choose how to write your app:

	Rust	TSX
Create	nsh init my-app --template rust	nsh init my-app --template ts
Write	Rust components, typed styles and signals	TSX components, Tailwind classes and signals
Iterate	Rebuild and restart on Rust changes	Hot updates that preserve state
Toolchain	nsh and Rust	nsh

You can also combine them (nsh init my-app --template mixed): TSX screens import your Rust components and modules. See Building with Rust for Rust apps and mixed projects.

Run either app on your chosen platform:

nsh run my-app --target ios        # iOS simulator; requires Xcode
nsh run my-app --target catalyst   # Mac Catalyst window on macOS

nsh run my-app --target android    # emulator or device; requires the Android SDK

nsh run my-app --target macos      # AppKit window

nsh run my-app --target windows    # Win32 window

nsh run my-app --target linux      # GTK 4 window

nsh run my-app --target gpui       # as GPUI apps that embed it show it

nsh run my-app --target web        # open in the browser

The Rust template includes a Cargo project with its root component in src/lib.rs. The TSX template includes App.tsx, nsh.json and tsconfig.json, with generated TypeScript declarations in .nsh/types for your editor. Logs and errors show in the terminal. What each platform needs: Installation.

Examples

Example	What it shows
examples/gallery-rs	The gallery written in Rust: an app with no TSX and no QuickJS
examples/rust-exports	A TSX app using a component, a module and a class of its own Rust crate
examples/gallery	A tour of what NSH supports: lists, navigation, forms, controls, gestures, animation, images, styles, text, web view and video, fetch
examples/counter	The smallest app
examples/hopper	A dark, tabbed dashboard built only from primitives: interactive canvas charts, sliders, menus, animation
examples/desktop	A desktop app with a title bar and menus of its own (nsh/desktop)
examples/embed-ios, examples/embed-android	NSH inside existing native apps, with a native component the app registers
examples/bench	Rust components against the same components in TSX

cargo run

Acknowledgements

NSH builds on the ideas of these projects:

• GPUI, Zed's UI framework: the typed units and geometry (Points, Point, Size, Bounds, Edges), SharedString, typed styles in Rust and much of the vocabulary of NSH's API.
• GPUI Kit: gpui-base's unstyled base components, which nsh-base follows in names and scope, and the Coding and Design Guides.
• shadcn/ui: the design tokens of NSH's theme, its default theme (neutral) and the cssVars theme files apps write or export from shadcn's themes and tweakcn.
• Solid: the reactive graph, signals, memos, effects, owners and context, which both the Rust and the TSX side of NSH run on.

License

Licensed under the Apache License, Version 2.0.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be licensed under Apache-2.0, without any additional terms or conditions.