Platform overview

NSH runs on phones, desktops, terminals and the web: iOS, Android, macOS, Windows, Linux, GPUI, the terminal and web pages. Each has a backend of its own that draws with the platform’s own UI, so an app is UIKit views on an iPhone, AppKit views on a Mac, GTK 4 widgets on Linux, GPUI elements in a GPUI app, character Cells in a terminal and HTML in a browser, with the platform’s text, input, accessibility and dark mode. Everything above the backend is shared: the reactive graph, the renderer, Taffy layout, the components and the native modules are the same Rust code everywhere, so one app runs on all of them. An app written in Rust is that code and your crate, with no JavaScript VM; a TSX app runs its modules on QuickJS on top of it (Building with Rust).

On every platform, an app is used the same two ways: packaged as an installable app of that platform (nsh package), or embedded in a native app of your own, whether the host links a Rust root or loads TSX at run time. You develop it with nsh run (Rust edits rebuild and restart the app, TSX edits are hot updates).

#At a glance

• GPUI draws apps with GPUI, the framework of the sibling project GPUI Kit, on macOS, Windows and Linux alike: it is the backend for embedding in GPUI and GPUI Kit apps, whose AppView they place in their own element tree. Standalone desktop apps run and are packaged with each OS’s own backend (AppKit, Win32, GTK 4).
• Terminal draws apps on the terminal’s grid of character Cells, in the terminal’s own colors, keyboard first and with the mouse: nsh run --target tui runs an app in the current terminal, and a ratatui app embeds one with AppView.
• Web renders apps as HTML in a browser page: nsh package --target web publishes a static site for any web server or CDN, with a Rust app’s engine and crate compiled to WebAssembly, and a page of your own embeds an app with createPlayer or an iframe. It also runs the live demos and the playground on this site.
• Mac Catalyst runs the iOS backend in an iPhone-sized window (390×844) on a Mac, for development. Select it with --target catalyst to see how an app looks on a phone.

#Develop and package

nsh run picks the machine’s own platform when you give no --target: AppKit on macOS, the GTK window on Linux and the Win32 window on Windows. Phones are reached from a computer: iOS from a Mac with Xcode, Android from macOS, Linux or Windows with the Android SDK (Installation).

A Rust app (its nsh.json names the "root" component) runs and packages from its directory: nsh builds the app’s own runner for the target, with your crate and no QuickJS. A TSX app names its entry:

# A Rust app, from its directory
nsh run --target macos             # or ios, android, windows, linux, tui, web, catalyst
nsh package --target macos         # or ios, ios-simulator, android, windows, linux, web

# A TSX app
nsh run App.tsx --target macos     # or ios, android, windows, linux, gpui, tui, web, catalyst
nsh package App.tsx --target macos

Each desktop OS packages apps with its own backend, built for the machine it runs on: package a Mac app on a Mac, a Windows app on Windows and a Linux app on Linux. Packaging covers every target’s output, signing and icons.

#Embed in a native app

A Rust host mounts a Rust root (Root::of::<App>()) as AppSource::Rust or App::Rust, and gives its engines the app’s UI sets with set_ui_sets, so TSX it loads imports the app’s own components and modules. Each view is one engine, and an app can show several. The host registers its own native views for apps to use on every platform (Native components).

#Writing for every platform

Most of an app needs no platform checks: elements, styles, layout and modules behave the same everywhere. Where platforms differ, NSH gives the difference one place (Platform-specific code):

• The environment says where the app runs: in Rust os(), idiom() and is_desktop() (nsh_core::prelude), in TSX platform.os, platform.idiom, platform.desktop and platform.select from nsh. The OS is iOS, Android, macOS, Windows, Linux or the web; in a terminal, the idiom is "terminal" and the OS the machine’s own.
• Platform-only props go in ios={{…}}, android={{…}}, web={{…}} or desktop={{…}} in TSX (desktop: macOS, Windows, Linux, desktop browsers and terminals).
• Input follows the platform. Phones get touches and the software keyboard; desktops get the mouse, the trackpad and the keyboard.

An app’s components are drawn with NSH’s primitives, so they run on desktops as well as on phones, looking the same on both. A desktop layout is built from the primitives (view, text, scroll, virtual_list, …; View, Text, Scroll, List, … in TSX) and a check for the desktop, as the gallery’s desktop layout is:

use nsh_core::prelude::*;

#[component]
pub fn Shell() -> impl IntoElement {
    // macOS, Windows, Linux and desktop browsers get a sidebar; phones get tabs.
    view()
        .flex_1()
        .child(if is_desktop() { sidebar_layout() } else { tab_layout() })
}

fn sidebar_layout() -> AnyElement {
    view().flex_1().flex_row().into_element()
}

fn tab_layout() -> AnyElement {
    view().flex_1().flex_col().into_element()
}

import { View } from "nsh";
import { platform } from "nsh";

export function Shell() {
  // macOS, Windows, Linux and desktop browsers get a sidebar; phones get tabs.
  return <View class="flex-1">{platform.desktop ? <SidebarLayout /> : <TabLayout />}</View>;
}

function SidebarLayout() {
  return <View class="flex-1 flex-row" />;
}

function TabLayout() {
  return <View class="flex-1 flex-col" />;
}

Each backend lists what it does its own way: macOS, Windows, Linux, GPUI, Terminal.

#See also

• Getting started: a first app, run on each platform.
• Building with Rust: apps written in Rust, and Rust with TSX.
• Installation: the tools each platform needs.
• Architecture: what is shared and what each backend does.