Native Shell

One app, written in Rust, in TSX, or in both, rendered through each platform's own views on the same Rust engine. Follow the user’s chosen language and delivery model. When neither is specified, prefer Rust for an app shipped in its binary.

Establish the App's Design System First

Before building feature screens, read the Design and Coding Guides and establish or reuse the app's design standards, semantic Theme Tokens and styled component library. Keep them in the app repository. nsh-base (nsh/base) supplies unstyled behavior, as gpui-base does; the styled layer analogous to gpui-component belongs to the app or its chosen community library.

Define theme colors centrally and consume semantic tokens throughout pages, components and states: theme() in Rust; token classes or token() in TSX. Do not introduce raw hex, RGBA/HSLA or palette classes in presentation code. Add missing roles to the theme first. User-selected or data colors remain data. Build complete styled controls for the feature's needs, then compose pages from them; extend shared variants instead of restyling base controls per screen.

Choose the app's Desktop, Mobile, Web and TUI targets explicitly. Adapt density, navigation, input and overlays to those targets, preserving shared semantics. TUI uses character Cells and terminal colors; Web follows the device's input. Review token use, component reuse and platform states before finishing. For a narrow change, extend the existing system within the requested scope.

Choose the Mode, Then Read Its Page

In an existing project, stay in its mode unless the user requests a change. For a new app, honor the requested mode; otherwise use the table above; a Rust app can gain TSX later, because it already has a #[native_module]. tooling.md covers the commands, debugging, platforms, capabilities, packaging and updates in all three.

The rule of every mode: a component runs once, and only the bindings that read a changed signal run again. A value read in a component body is a snapshot.

First App or Existing Project

Resolve references/ paths relative to this skill’s directory, not the app’s working directory. Read only the mode and topic pages needed for the task.

• Existing project: inspect nsh.json, the entry and, for Rust, Cargo.toml. Keep its structure, dependency sources and mode. Use the project’s CLI version.
• First app: run nsh --version. For Rust or mixed, also check cargo --version. If a tool is missing, read tooling.md for setup and the prerequisites of the requested target.
• Read the guides below and the selected mode page. Initialize with the table’s explicit --template in the user’s chosen location. Work from the generated project, preserving its manifest and entry wiring; the quick-start snippets below illustrate edits, rather than replacing all generated files.
• Get the generated app through nsh check and nsh test before expanding it. Then implement the requested flow and use the mode’s verification loop below. Check the visible result on the requested target when available; report any verification that the environment cannot perform.

Read the Guides First

Two guides hold the rules this skill assumes. They are requirements, not inspiration. Read the guide file itself; do not answer from this page, from a similar file in the codebase, or from training data.

Read the Design Guides first when the change has a visible surface. If the design skill is not installed, fetch https://nsh.dev/docs/design-guides.md. The coding guide is a verbatim copy of https://nsh.dev/docs/coding-guides.md, so a link in it such as ./reactivity.md means https://nsh.dev/docs/reactivity.md, and ../modules/nsh.md means https://nsh.dev/modules/nsh.md.

Coding Guides section map

Read the whole guide for a new app, module or feature. For a narrow change, read "Understand what runs once and what runs again" and "Rules for coding agents" first, then the section for the change (grep -n '^## ' references/coding-guides.md).

Non-negotiables

A floor, not a substitute for the guides.

• Never invent an API. Look the name up in the crate's source (Rust) or in .nsh/types (TSX), then its reference page. Do not write by analogy with another framework.
• Components run once. In Rust, pass a closure or a signal where a value must stay current: text(move || format!("{}", count.get())). In TSX, read props and signals in JSX or a closure; do not destructure props.
• One owner per state. A page's draft is a signal of that page; shared state is a store with private signals. In Rust with TSX, one side owns each piece of state.
• The look is the app's. nsh_base / nsh/base has behavior and no look, and NSH has no styled component library. Draw with theme tokens: theme().primary in Rust, bg-primary in TSX. Wrap each base component once in the app's own UI module.
• Parts draw nothing until styled. A switch with no track and thumb style shows no switch, and a test still passes. Style every part, and look at the result.
• Use the semantic component. Button, Menu, Popover, Sheet, Dialog and Select bring focus, keyboard, dismissal and accessibility. Do not rebuild them from a view.
• Use a virtualized list by default for collections that can grow, including chat, feeds and history: List in TSX, virtual_list in Rust. Use Scroll and Each for small, bounded content. Keep per-item state in data keyed by id, never in a signal created in a row: cells are reused for other rows. Test recycling and off-screen jumps, and preserve the visible position as data changes.
• A decision the system needs at once is a prop, set beforehand (pop_on_back, close_on_escape, disabled), never a callback returning a boolean.
• Do not change NSH to fit an app. Solve it in the app first: its own components, a Rust crate, or a native component.
• TSX has no DOM, no Node and no npm UI. Standard modules are exactly buffer, console, crypto, fs/promises, net, os, path, process, url, websocket, zlib.

The Loop

Run your mode's loop before calling work done. Prefer check and headless tests to full builds while working.

# Rust
cargo check --all-targets   # or nsh check, which also checks TS tests
cargo test                  # the real UI, headless, with nsh_testing::Headless
nsh run                     # look at it; --target ios, android, web, macos, linux, windows

# Rust with TSX
nsh check                   # cargo check, then tsc against the types generated from Rust
nsh build                   # every warn is a finding: undocumented exports, unknown classes
nsh test                    # cargo test, then *.test.tsx in a runner linked with the crate
nsh run

# TSX
nsh check                   # the only type check
nsh build                   # the bundler's errors: nsh check does not see text in a View
nsh test                    # *.test.tsx, headless
nsh run

Headless tests prove behavior, not the look: take a screenshot or run the app for anything visible. In TSX, passing one of nsh check and nsh build proves little without the other; the table in tsx.md shows who reports what.

Quick Start in Rust

use nsh_base::{button, theme};
use nsh_core::prelude::*;

#[native_module("app/native")]
fn native(registry: &mut Registry) {
    registry.register::<App>();
}

#[component]
pub fn App() -> impl IntoElement {
    let count = signal(0_u32);
    view()
        .flex_1()
        .items_center()
        .justify_center()
        .gap_4()
        .bg(move || theme().background)
        // A closure is a binding: it runs again when `count` changes.
        .child(text(move || format!("Count: {}", count.get())).text_color(move || theme().foreground))
        .child(
            button()
                .px(px(20.0))
                .py(px(12.0))
                .rounded(move || theme().radius)
                .bg(move || theme().primary)
                .active(|s| s.bg(move || theme().primary.opacity(0.9)))
                .on_press(move || count.update(|c| *c += 1))
                .child(text("Tap").text_color(move || theme().primary_foreground)),
        )
}

{ "name": "My App", "rust": ".", "root": "App" }

// tests/app.rs (add matching dev-dependencies from references/rust-testing.md)
use nsh_engine::{EngineConfig, Root};
use nsh_testing::Headless;

#[test]
fn a_tap_counts() {
    let mut app = Headless::start(EngineConfig::new(Root::of::<nsh_app_my_app::App>())).unwrap();
    app.wait_for("Count: 0").unwrap();
    app.press("Tap").unwrap();
    app.wait_for("Count: 1").unwrap();
}

The same app in TSX, and the TSX forms, are in tsx.md. snake_case Rust names are camelCase in TSX (on_open_change is onOpenChange).

Documentation

Start with the bundled mode pages and recipes; they work without an NSH checkout. For exact APIs, use the project’s .nsh/types in TSX and its resolved dependency source in Rust. cargo metadata --format-version 1 reports dependency manifests and their source locations; use those paths rather than assuming a Cargo cache path. Run nsh check to generate missing TS declarations.

Paths starting with examples/, crates/ or website/ in the references identify files in the NSH repository; they are optional source pointers, not files in the installed skill or the user’s app. Use them when a checkout is available. Otherwise, use the bundled recipes, the online docs below, or the corresponding file at https://github.com/longbridge/nsh at the project’s matching tag or revision. A website/docs/foo.md pointer corresponds to https://nsh.dev/docs/foo.md; website/elements/ and website/modules/ similarly map to site paths.

The site follows the latest release and may describe a newer API than the project uses. Preserve the project’s version and verify examples against its types or source. Fetch individual pages as needed; use llms-full.txt only for broad exploration.

• Find a page: https://nsh.dev/llms.txt, then load its Markdown; https://nsh.dev/llms-full.txt for broad reference.
• Rust: https://nsh.dev/docs/rust.md, native-components.md, networking.md.
• An element or component: https://nsh.dev/elements/{name}.md.
• A module: https://nsh.dev/modules/{name}.md: nsh.md, nsh-base.md, nsh-mobile.md, nsh-desktop.md, style-reference.md, tailwind-reference.md, standard-modules.md.
• A guide: https://nsh.dev/docs/{name}.md: reactivity.md, layout.md, navigation.md, lists.md, forms-and-keyboard.md, platform-specific.md, testing-and-trace.md.

Working on NSH itself

This skill is for building apps. In a checkout of longbridge/nsh, follow its AGENTS.md and docs/dev/ as well.