# Introduction

> What NSGo is, what it runs on and how it works.

NSGo is a cross-platform native UI framework written in Go. You write an app once, in Go or in TSX, and it runs on iOS and its App Clips, tvOS, watchOS, Android, macOS, Windows, Linux and the web, drawn by each platform's own views. Go apps also run in WeChat, QQ, Alipay and Douyin mini programs, experimentally: the platforms hold an app to 2 MB, which larger apps exceed.

## What you write

An app is a Go main package. Its components return elements: views, text, images, inputs and the controls in `ui`. State lives in signals, and only what reads a signal updates when it changes.

```go
func Root(cx *core.Scope) core.Node {
	count := core.NewSignal(cx, 0)
	return core.View{Style: core.Style{Padding: core.All(24), Gap: 12}, Children: []core.Node{
		core.Text{ContentFunc: func() string { return fmt.Sprintf("Pressed %d times", count.Get()) }},
		ui.Button{Text: "Press me", OnPress: func() { count.Update(func(n int) int { return n + 1 }) }},
	}}
}
```

The same app can be written in TSX and styled with Tailwind classes ([TSX apps](https://nsgo.dev/docs/tsx.md)).

## How it works

A Go engine owns the app: the reactive graph, styles, flexbox and grid layout, and text preparation. Each update produces one batch of changes, and a thin backend applies it to the platform's native views. Animation runs on the platform's frame clock, so nothing commits once a frame.

| Platform | Draws with |
| --- | --- |
| iOS | UIKit and CoreText |
| Android | Android Views |
| macOS | AppKit and CoreText |
| Windows | Direct2D and DirectWrite |
| Linux | GTK 4, Pango and Cairo |
| Web | WebAssembly and DOM elements |

Every target builds on a Mac with Go; iOS also needs Xcode. The `nsgo` tool creates, runs, tests and packages apps.

## Status

NSGo is early: it has no stable API or release yet, and what is missing is in the [roadmap](https://github.com/nsgo-dev/nsgo/blob/main/docs/roadmap.md). It ports the design of [Native Shell](https://github.com/longbridge/nsh) to Go.

## How to read the docs

Every page answers one question. A code example is a fragment of a component unless the page says otherwise: `cx` is the `*core.Scope` a component receives. Apps use `ui`'s components, which have a look; `base` holds the same controls without a look, for authors of components.

- **Get started**: [setup](https://nsgo.dev/docs/getting-started.md), then example apps built step by step, [a todo app](https://nsgo.dev/docs/tutorials/todo.md), [a notes app](https://nsgo.dev/docs/tutorials/notes.md) and [popular GitHub repositories](https://nsgo.dev/docs/tutorials/repos.md).
- **Toolchain**: [running and debugging](https://nsgo.dev/docs/debugging.md), [testing](https://nsgo.dev/docs/testing.md), [building and shipping](https://nsgo.dev/docs/building.md) and [embedding](https://nsgo.dev/docs/embedding.md).
- **Components**: [the most-used components](https://nsgo.dev/docs/ui.md), their variants, states and accessibility.
- **Core concepts**: [components and state](https://nsgo.dev/docs/components.md), [layout](https://nsgo.dev/docs/layout.md), [styles](https://nsgo.dev/docs/styles.md), [text](https://nsgo.dev/docs/text.md), [lists](https://nsgo.dev/docs/lists.md), [navigation](https://nsgo.dev/docs/navigation.md), [forms](https://nsgo.dev/docs/forms.md), [localization](https://nsgo.dev/docs/localization.md), [TSX](https://nsgo.dev/docs/tsx.md) and the rest.
- **Platform features**: [platform services](https://nsgo.dev/docs/services.md), [notifications](https://nsgo.dev/docs/notifications.md), [haptics](https://nsgo.dev/docs/haptics.md), [widgets](https://nsgo.dev/docs/widgets.md), [Live Activities](https://nsgo.dev/docs/live-activities.md) and [permissions](https://nsgo.dev/docs/permissions.md).
- **Writing components**: [components for other people's apps](https://nsgo.dev/docs/authoring.md), unstyled and styled.
- **Contributing**: [build NSGo from source](https://nsgo.dev/docs/contributing.md), find your way around it and send a change.
- The [live demo](https://nsgo.dev/gallery/): every component, in your browser.