nimbus-native

Nimbus Native

Native iOS and Android apps written in Go, and the same app on the web. Your app's Go code is compiled into the app and drives real native views — UIKit on iOS, Android Views on Android — laid out by a flexbox engine written in Go. Nimbus is the server, and serves the app's pages to browsers too. One language, one codebase, backend included.

Beta (0.0.10). Everything below runs on the iOS simulator, the Android emulator, in browsers and on a real iPhone; no app has shipped to a store yet, and APIs may still change. See CHANGELOG.md for what's in it and what isn't yet.

go install github.com/CodeSyncr/nimbus/cmd/nimbus@latest   # Nimbus v1.16.0 or later
nimbus native new myapp
cd myapp
nimbus native dev ios            # the app, plus the server and web app on :3333; reloads on save

type Counter struct{}

func (Counter) Render(c *ui.Ctx) ui.Component {
	n, setN := ui.State(c, 0)
	return ui.SafeArea(ui.Style{Padding: ui.All(16)},
		ui.Pressable(func() { setN(n + 1) }, ui.Style{Padding: ui.All(12)},
			ui.Text(fmt.Sprintf("Tapped %d times", n), ui.Style{FontWeight: 600}),
		),
	)
}

func init() { ui.Mount(Counter{}) }

func main() { ui.Main() } // runs only in dev mode; on a device the host owns the process

Requirements

• Go 1.26+ for a project with a Nimbus server (Nimbus needs it; 1.23+ for the app alone), and the nimbus CLI v1.16.1+ from Nimbus
• iOS: macOS with Xcode 16+. nimbus native run ios runs on a connected iPhone or iPad (USB, or Wi-Fi once paired in Xcode's Devices window, with Developer Mode on) and on the simulator when none is. With several, it asks which; the first phone run asks which Apple team signs it and saves that in the Xcode project. -sim forces the simulator, -udid picks a device, -team a team.
• Android: the Android SDK with an NDK and build-tools, JDK 17+. The Kotlin compiler is downloaded on the first build.

nimbus native run android likewise prefers a connected phone, then a running emulator, then boots the first one. nimbus native doctor checks all of it. Release Android builds are signed with the debug key until you add yours to native/android/app/build.gradle.kts.

Layout

Start a project

nimbus native new myapp         # asks: a Nimbus server or your own backend; database, auth, plugins
cd myapp
nimbus native dev ios           # the app on a phone or simulator, plus the Nimbus
                                # server and web app on :3333, reloading on save
nimbus native dev android       # the same on Android
nimbus native run ios           # a normal build, installed and opened; or open
                                # native/ios/Runner.xcodeproj in Xcode

The generated app is a counter, ready to grow: one polished screen (a goal with a progress bar, steps, the count saved between launches, light and dark themes) on iOS, Android and the web.

new asks what the app talks to. A Nimbus server (the default) makes a whole Nimbus app, with the same questions and files as nimbus new (.env, config/, start/, controllers, migrations), and adds the native app to it; the server also serves the app's pages on the web. Your own backend (-server none) makes the phone app alone, for a Node, Go or any other server: the app calls it with api.New("https://…") over HTTP and JSON. Flags skip the questions: -y (defaults), -server, -db, -auth, -plugins.

A project with a Nimbus server is one Go module:

myapp/
  main.go, bin/            the Nimbus server's entry and boot
  start/routes.go          your routes and API; start/native.go serves the app's pages
  config/, .env            Nimbus configuration
  app/
    controllers/, models/  the server's code (never in the phone app)
    app.go                 the app's root component; installs the theme
    mobile/main.go         the phone app's package main
  core/                    constants, theme
  features/counter/
    data/                  the counter's state (a ui.Store), saved on the device
    presentation/          the screen
  pages/page.go            the page at "/" (folder routing: pages/settings/ is /settings)
  database/, public/       migrations; static files and fonts for the web
  native/
    ios/                   Xcode project (Runner + the NimbusNativeKit package)
    android/               Gradle project (app + the nimbusnativekit module)

Without a Nimbus server it is the same minus the server's files. As the app grows, add shared/ (widgets, services) and give features a domain/ package (types and api.Endpoints: the contract between app and server).

The server builds with CGO_ENABLED=0 (for a Linux container, say); only SQLite needs cgo, as in any Nimbus app.

Xcode and Gradle build the hosts as usual; a build step in each runs nimbus native lib, which builds app/mobile into the native library and writes the generated Swift or Kotlin. It also keeps the project's copy of the host kit at the version go.mod requires (after an upgrade, the first build updates it and asks you to build again), and refuses to build a phone app that imports Nimbus or any server package: that code stays on the server.

To move a project to a newer release:

nimbus native upgrade            # or: nimbus native upgrade v0.0.10

It updates go.mod, then the new release copies its kits into native/ and regenerates the Swift. Your own files under native/ are left alone; the changelog says when a release wants something changed there.

Icons, launch screens and store builds

nimbus native icon logo.png -background "#6d28d9"   # iOS + Android icons; -launch sets the launch color
nimbus native keystore                              # once: the Android release (upload) key, kept out of git
nimbus native build android -release -version 1.0.0 -build 1   # build/android/release/<App>.aab and .apk
nimbus native build ios -release -version 1.0.0 -build 1       # build/ios/release/<App>.ipa for App Store Connect

New projects start with an icon and launch screen in the app's colors. The icon is any square PNG or JPEG, 1024 px or more: iOS gets one flattened App Store icon, Android an adaptive icon for every density.

iOS releases sign automatically with your team (-team, or the one saved in the Xcode project). App Store export needs the Apple ID in Xcode to have the Admin or App Manager role; -export ad-hoc and -export development make an .ipa for registered devices. Upload with Xcode's Organizer or Transporter. Android release builds use the key from nimbus native keystore; without one they fall back to the debug key, which Google Play refuses (the build says so).

Folder routing

Optional: a project with a pages/ folder gets its URLs from it.

pages/orders/page.go             /orders
pages/orders/new/page.go         /orders/new    (beats :id)
pages/orders/_id/page.go         /orders/:id
pages/orders/_id/items/_item/    /orders/:id/items/:item

Each page.go declares a Page component; parameters fill fields tagged param (string, int or int64; a value that doesn't parse matches nothing), and an optional Title() names the screen:

package order // pages/orders/_id

type Page struct {
	ID int `param:"id"`
}

func (p Page) Title() string                  { return fmt.Sprintf("Order #%d", p.ID) }
func (p Page) Render(c *ui.Ctx) ui.Component { return presentation.OrderScreen{ID: p.ID} }

Every build regenerates pages/routes_gen.go, a static table: no reflection or scanning at run time, and a missing or mistyped parameter field fails the build with the folder named. Register it once, then navigate by path; the page is pushed onto the screen's native stack:

router.Register(pages.Routes)   // app/router.go
router.Push(c, "/orders/42")    // any screen

Go skips _-prefixed folders in ./... patterns, so go vet ./... passes over parameter pages; they are compiled through the table the app imports.

Shared state

ui.Store is state the whole app shares, such as a cart or who is signed in: one value per app on a phone, and one per browser tab on the web (where every visitor runs in the same server, so a package variable would be shared between them).

var Cart = ui.NewStore(func() Cart { return nil })

items := Cart.Use(c)                                          // re-renders c when it changes
Cart.Update(c, func(ct Cart) Cart { return ct.Add(p) })       // from handlers, effects, actions

Controls and dialogs

ui.Switch(on, setOn, ui.Style{})                                   // UISwitch / Switch, theme-tinted
ui.TextInput(note, setNote, box).Multiline()                       // or FieldOptions{Multiline: true}
ui.List(n, row, ui.Flex(1)).OnRefresh(q.Loading, q.Refetch)        // pull to refresh (Scroll too)

ok, _ := dialog.Confirm(ctx, "Delete order?", "This can't be undone.", "Delete", true)
i, _ := dialog.Choose(ctx, "Share via", "Mail", "Messages")        // action sheet; -1 if cancelled
dialog.Toast(ctx, "Saved")
day, ok, _ := dialog.PickDate(ctx, dialog.Date, time.Now())        // Date, Time or DateTime

More: ui.Slider(value, min, max, onChange, style) (UISlider, SeekBar, a range input on the web); .OnLongPress(fn) on a Pressable (a right click on the web); Style{Wrap: true} for rows that wrap onto new lines (chips, tags), with LineGap between lines; and Style{Transition: 250} to animate a view's changes of position, opacity and background over 250 ms.

SafeArea keeps clear of the on-screen keyboard: its bottom padding grows by however much of the keyboard reaches below it.

Fonts

nimbus native font add Inter.ttf bundles a font in the iOS and Android apps (and serves it to the web); use it as ui.Style{FontFamily: "Inter"}. The family is the file name; weights come from FontWeight.

Links into the app

Every project has a URL scheme, its module name: myapp://orders/42 opens the app on /orders/42, at launch or while it runs, pushed on the navigation stack on screen (or as a sheet where there is none). Set ui.HandleURL to decide yourself.

The web

A project's Nimbus server also serves its pages to browsers (main.go mounts web.Handler as the router's fallback):

• Server rendering. A request runs the page's components on the server, waits for its UseQuery data (up to 3 s), and answers with plain HTML: content, links (router.Link, .Href), and the page's <title>, description, Open Graph tags and canonical URL from its Head() method. /sitemap.xml lists the pages without parameters; /robots.txt points to it.
• Then live. host.js (12 KB, 4 KB gzipped) adopts that HTML. Taps and typing go to the page's UI session on the server, and what it renders comes back as DOM changes over Server-Sent Events. Layout is the browser's own flexbox.
• Navigation. On the web the shell is app.WebLayout, a header with a link per tab, instead of tabs and stacks. router.Push changes the page and the address; Back and Forward work; every page has its own URL.

func (p Page) Head() router.Head {
	return router.Head{Title: fmt.Sprintf("Order #%d", p.ID), Description: "…", Image: "https://…/og.png"}
}

Each open tab holds a small UI session on the server, closed a minute after the tab goes away. Native plugins answer unavailable on the web.

Plugins: calling native code

Install a third-party plugin module

Plugins can be shared as Go modules and installed by module path, with an optional pinned version:

nimbus native plugin add github.com/acme/native-battery@v1.2.0
nimbus native plugin list
nimbus native plugin remove battery

The module root contains plugin.json, its Go API, and ios/*.swift and android/*.kt handlers. The manifest declares the plugin name, description, handler, and any iOS usage descriptions/Swift packages or Android permissions/ Gradle dependencies. The Swift handler is a type with the declared name; the Kotlin handler is an object with that name in space.nimbusgo.nativekit. Nimbus stages those native files under native/plugins/<name>, records enabled plugins in native/plugins.json, and adds the module to go.mod. Commit those files with go.mod and go.sum. Without @version, the CLI resolves the module's latest version; pin a version for repeatable builds. Set the optional go field in the manifest to a subpackage import path if the Go API is not in the module root. An Android plugin can also declare android.native libraries to compile C/C++ sources under android/ for each ABI. After removing a plugin, run go mod tidy if its Go API is no longer imported.

Go reaches Swift and Kotlin through plugins. Built in:

securestore.Set(ctx, "token", t)            // Keychain / Android Keystore
token, ok, err := securestore.Get(ctx, "token")
storage.Set(ctx, "theme", "dark")            // JSON in the app's data folder
info, _ := appinfo.Get(ctx)                  // version, locale, data and cache dirs
linking.Open(ctx, "https://example.com")     // browser, tel:, mailto:, maps

Your own plugin is a name and a handler in the host, and one call in Go. Arguments and answers are JSON, so neither side needs generated code:

// native/ios/Runner/AppDelegate.swift, before the NimbusViewController
Plugins.register("battery") { call in
    UIDevice.current.isBatteryMonitoringEnabled = true
    call.resolve(["level": UIDevice.current.batteryLevel])
}

// native/android/.../MainActivity.kt, before the NimbusView
Plugins.register("battery") { call ->
    val bm = getSystemService(BATTERY_SERVICE) as android.os.BatteryManager
    call.resolve(mapOf("level" to bm.getIntProperty(android.os.BatteryManager.BATTERY_PROPERTY_CAPACITY) / 100.0))
}

type battery struct{ Level float64 `json:"level"` }
b, err := plugin.Call[battery](ctx, "battery", "level", nil)

Handlers run on the main thread and answer once with resolve or reject(code, message); codes (cancelled, denied, not_found, unavailable, failed) come back as plugin.Error, testable with plugin.IsCode. plugin.Call blocks its goroutine until the answer, so call it from ui.UseQuery, ui.UseAction or an effect, not in Render. Plugins work unchanged under nimbus native dev.

On Android, fmt.Println and log output goes to logcat (tag NimbusNativeApp), which nimbus native run android streams.

Try the examples

Everything goes through the nimbus CLI — there is no second tool:

nimbus native doctor
nimbus native dev ios ./examples/gallery       # hot reload: edit, save, see it
nimbus native run ios ./examples/gallery       # boots a simulator if needed
nimbus native run android ./examples/gallery   # boots the first AVD if needed
nimbus native build ios|android ./examples/gallery
nimbus native gen ./examples/hello             # every build does this too

nimbus native runs the toolchain (cmd/nimbus-native) at the version the app's go.mod requires, so the CLI always matches the app's runtime. Outside such a module it runs the latest release, or NIMBUS_NATIVE_BIN if set.

run streams the app's log until you press Ctrl+C.

Typed messages: the wire schema

An app describes what crosses the bridge as plain Go types in a package of its own (the hello app uses examples/hello/proto):

//wire:message
type Hello struct{ Name string }

//wire:enum
type Kind uint8

//wire:union
type Op interface{ isOp() }

//wire:variant Op
type Remove struct{ ID uint32 }

nimbus native gen (run by every build) writes wire_gen.go next to the schema (proto.Encode, proto.Decode, methods on each type) and the same types for the hosts: Proto.Message.hello(Proto.Hello(name: "Yash")) in Swift, Proto.Hello(name = "Yash") in Kotlin. Supported: bool, every int and uint size, float32/64, string, []byte, lists, maps with string or integer keys, optionals (*T), nested structs, recursion through lists ([]*Node), unions, open enums.

The encoding is compact binary (varints, zigzag, little-endian floats, sorted map keys; spec in wire/wire.go). Each schema has a hash; the host passes the combined hash to nn_start, which refuses a mismatch with NN_ERR_SCHEMA. go test ./wire/gen proves the three languages agree: Go encodes every kitchen-sink fixture plus corrupt variants, and compiled Swift and Kotlin programs must decode and re-encode them to identical bytes and reject the same bad inputs.

Android is Kotlin

The Android kit, generated wire types and example activities are Kotlin. nimbus native downloads a pinned Kotlin compiler (2.0.21, SHA-256 checked) into the user cache on the first Android build; NIMBUS_KOTLINC points it at another. Plain Java activities still build alongside.

How a build works

Projects build with xcodebuild and Gradle (the IDEs' own builds). The examples build with the platform tools directly:

• iOS: go build -buildmode=c-archive (GOOS=ios, Xcode clang) → libapp.a, then swiftc links it with the host and app Swift code, writes Info.plist, ad-hoc signs the .app.
• Android: go build -buildmode=c-shared (NDK clang, 16 KB pages) → libnimbusapp.so per ABI, then kotlinc + d8 (with the Kotlin standard library) → classes.dex, aapt2 → APK, native libs stored uncompressed, zipalign -P 16, apksigner.

How the bridge moves messages

• Native → Go: nn_send (async, in order) or nn_call (sync, returns a reply). A Go panic in nn_call comes back as NN_ERR_PANIC with the panic text and Go stack — BridgeError on iOS, BridgeException on Android.
• Go → native: bridge.Send appends to an outbox and never blocks. Only when the outbox goes from empty to non-empty does Go call the host's wake; the host then calls nn_drain on its UI thread and gets every waiting message in one buffer. A burst costs one thread hop, not one per message.
• Hosts refer to Go values by integer Handle, never by pointer.

Dev mode

 laptop                                        simulator / emulator
 nimbus native dev ── relay :7357 ◄──TCP──►   dev shell: the real app, its Go
   │ your app, built for the laptop            library swapped for a proxy
   └ restarted on every save                   (dev/client); native code as shipped

nimbus native dev ios|android builds a dev shell once, then runs the app's Go code on the laptop (-tags nimbusdev: the same bridge API over a socket). Saving a .go file rebuilds and restarts it; the shell clears the old views and the new process renders. A compile error is printed and the last good build keeps running. A wire-schema change rebuilds the shell. The relay caches the device's text measurements, so a reload re-measures nothing. Android reaches the relay through adb reverse.

In a project, dev also runs the Nimbus server (go run .) and restarts it on every save, so the web app and your API stay current too; it takes the next free port when 3333 is busy, o opens it in the browser, and -no-server leaves it out. On Android the app reaches it through adb reverse, at the device's own 127.0.0.1.

While it runs, the terminal shows the app's output (app │ lines from the Go process, device │ lines from the simulator or emulator), panics and errors in red, a line when an app process stops, and how long each reload took to reach the screen. Single keys work as well as saving:

r  reload    R  restart (rebuild and reinstall)    o  open the web app    c  clear    q  quit    h  help

Measured on the gallery (1,000 rows): a save is on screen in 1.9–3.5 s on the iOS simulator and 2.7 s on the Android emulator, of which 0.6–2.3 s is compiling — this Mac runs the Intel build of Go under Rosetta; the Apple Silicon build compiles roughly twice as fast.

Like run, dev puts the shell on a connected phone when there is one (-sim for the simulator or emulator). An iPhone reaches the relay over Wi-Fi, so iOS asks once to let the app find devices on the local network; Android phones go through adb reverse.

In a project, nimbus native dev ios|android builds the shell with the project's own Xcode or Gradle build and watches the whole module (not native/ or build/), so a new page folder is live on the next save. Component state starts fresh on each reload, but the screen doesn't: the selected tabs and every screen pushed with router.Push come back. Each dev session starts on the first screen.

How a screen gets drawn

1. A state change (or host event) is queued to the UI loop goroutine.
2. Components whose props or state changed render again; the rest are kept.
3. The keyed reconciler turns the new elements into ops — create, children order, style, text, image, input — only for what changed.
4. The flexbox engine lays out only changed subtrees, asking the host to measure text (a synchronous host call, cached per text).
5. Changed frames join the ops in one render.Commit, applied on the UI thread in a single pass.

Navigation

ui.Stack("Orders", OrdersScreen{}, ui.Flex(1))   // the app's root

nav := ui.Navigation(c)                          // in any component on a screen
nav.Push("Order #10012", OrderDetail{o})
nav.Pop()

The stack is native: UINavigationController on iOS (its bar, push animation and swipe-back), a Material-style bar with a back arrow, slide transitions and the system back button on Android (onBackPressed → renderer.back()). Go owns the screens; when the user goes back, the host tells Go (Popped) and the two stay in step. Each screen's content is Go-rendered at the size the host reports.

Tabs work the same way: ui.Tabs(style, ui.Tab{Title, Icon, Screen}...) is UITabBarController on iOS (SF Symbol icons) and a bottom bar on Android; every tab stays mounted; ui.TabsOf(c).Select(i) switches from Go and a user's tap is reported back. ui.SafeArea pads clear of the status bar, home indicator and tab bar.

Modals: ui.Modals(c).Present(title, screen) shows a page sheet on iOS (swipe down to close) and a full-screen layer on Android (back to close); each has its own stack and title bar, so Navigation works inside it. ui.Modals(c).Dismiss() closes it from Go, and a user's close is reported back.

Talking to a Nimbus server

// shared/api.go — imported by the Nimbus server and the app
var ListOrders  = api.GET[ListOrdersReq, []Order]("/api/orders")
var CreateOrder = api.POST[NewOrder, Order]("/api/orders")

// in the app
client := api.New(api.ServerURL("https://orders.example.com"))
q := ui.UseQuery(c, "orders", func(ctx context.Context) ([]Order, error) {
	return api.Call(ctx, client, ListOrders, ListOrdersReq{})
})
place := ui.UseAction(c, func(ctx context.Context, o NewOrder) (Order, error) {
	created, err := api.Call(ctx, client, CreateOrder, o)
	form.SetErrors(err) // a Nimbus 422 lands on the form's fields
	return created, err
}, func(Order) { ui.RefetchQuery(c, "orders") })

The api package depends only on the standard library, so shared code that imports it builds into the app without pulling in the server. An endpoint's method, path and request/response types are declared once; {name} path parameters come from fields tagged path:"name", GET/DELETE requests become query parameters and the rest JSON bodies. A non-2xx response is an *api.Error; a Nimbus 422's field errors come with it. ui.UseQuery fetches off the UI goroutine, caches by key across components, refreshes stale data in the background and refetches on demand; ui.UseAction runs writes with their progress and result. See examples/fullstack for a Nimbus server and app sharing one contract.

api.ServerURL finds the server wherever the app runs. Under nimbus native dev it's the server running beside the app. A nimbus native run uses the project's server on this Mac at an address the target can reach: the simulator's 127.0.0.1, the emulator's 10.0.2.2, or this Mac's address on the local network for a phone (start it with nimbus serve). Any build takes -server https://your-server, built into the app; a release build warns when a project with a server has none. The argument to ServerURL is the fallback.

Theming and dark mode

ui.Theme holds an app's tokens (background, surface, text, muted, border, primary, danger, bar colors, radius, type and spacing scales); ui.LightTheme / ui.DarkTheme are built in and ui.SetTheme(light, dark) replaces them. The runtime follows the system's dark mode: ui.UseTheme(c) re-renders with the other theme, unset text, input and spinner colors take the theme's, and the Chrome op restyles what the platform draws — navigation and tab bars, screen and modal backgrounds, Android's status and navigation bars.

Forms

form := ui.UseForm(c, Signup{}, validation.ValidateStruct) // a Nimbus server's own rules
ui.TextField(form.Field("email", func(s *Signup) *string { return &s.Email }),
	ui.FieldOptions{Label: "Email", Keyboard: render.KeyboardEmail})
ui.Pressable(form.Submit(save), style, ui.Text("Sign up", style))

UseForm takes any func(T) error; field errors come from ui.FieldErrors, Nimbus's validation.ValidationErrors or anything with ToMap() map[string][]string — so one rule set validates both the server and the app, without Nimbus Native importing Nimbus. Errors show once a field is touched, and for every field on submit; submit runs only when the value is valid. ui.FieldErrorsOf(err) reads a server's 422 the same way.

Lists

ui.List(count, item, style) renders only the rows on screen and about one screen above and below; rows can differ in height (each is measured once shown). Scrolling renders no app components — only rows entering and leaving — and re-windows only when the screen nears the edge of what is rendered.

Phase 0d results

* The emulator is the limit here: the same list built with plain Android views scrolls at the same rate. First render is slow because all 1,000 rows exist as native views and measure their text; a virtualized list (Phase 1) creates only the visible rows.

Phase 0c results

* Emulator timings are not trustworthy (see below); a real device is next.

Phase 0b results

* The emulator was under heavy load (the 0a build measured 14–19 µs per sync call in the same session). Run back to back, 0b was no slower than 0a. Real Android latency needs a device.

Phase 0a results (M1, Go 1.23.3)