# Undra

> Undra is a Rust framework that owns everything under the pixels of native iOS, Android and web apps: domain logic, reactive state, the data layer, persistence and the dev loop. It generates idiomatic Swift, Kotlin and TypeScript from one Rust core, and the UI stays SwiftUI, Jetpack Compose and React. Not to be confused with undra.sh (Kubernetes) or undra.so.

Undra is open source (MIT OR Apache-2.0) and ships an `undra` CLI (`undra init`, `undra dev`, `undra build`, `undra bindgen`, `undra doctor`). Reads never cross the language boundary: each platform holds a mirror of the state, updated by one binary change-set per transaction.

## Docs

- [Undra documentation](https://shreypdev.github.io/undra/docs/): Guides and reference for Undra, the Rust framework for native iOS, Android and web apps: getting started, concepts, queries, ports, the CLI and the API.
- [Getting started · Undra docs](https://shreypdev.github.io/undra/docs/getting-started.html): Install the Undra CLI with the installer or cargo, make a project, run its web app in minutes, then the live loop, iOS and Android.
- [Core concepts · Undra docs](https://shreypdev.github.io/undra/docs/concepts.html): Stores, signals, computeds, transactions, change-sets and keyed lists, and why a list write costs the change and not the list.
- [Queries & mutations · Undra docs](https://shreypdev.github.io/undra/docs/queries.html): The data layer in the core: cached queries with staleness and dedup, retry, optimistic mutations with precise rollback, persistence and an offline queue.
- [Ports & adapters · Undra docs](https://shreypdev.github.io/undra/docs/ports.html): The ten standard ports, the default adapter on each platform, how to supply your own, what happens when one is missing, and the fakes for tests.
- [Objects and identity · Undra docs](https://shreypdev.github.io/undra/docs/objects.html): Methods that return and take objects: the Rust spelling, each platform's class, why one object is always one wrapper, and what an object cannot be part of.
- [Host callbacks · Undra docs](https://shreypdev.github.io/undra/docs/callbacks.html): Traits the app implements so the core can call it: where each call runs, how errors and cancelling cross, and how long the core holds a listener.
- [Newtypes, generics and decimals · Undra docs](https://shreypdev.github.io/undra/docs/types.html): Newtypes that stay typed on every platform, named generic types, an exact Decimal for money, and the types of uuid, chrono, time, rust_decimal and bytes.
- [Generic functions, objects and stores · Undra docs](https://shreypdev.github.io/undra/docs/generics.html): One piece of Rust over several row types: generic functions become overloads, generic objects and stores one ordinary class per alias.
- [Paging and lazy lists · Undra docs](https://shreypdev.github.io/undra/docs/paging.html): Infinite queries that grow a keyed list a page at a time, and Lazy lists the platform pages through on demand: the shapes, and what a change costs.
- [Polling · Undra docs](https://shreypdev.github.io/undra/docs/polling.html): Refetch a query on an interval while somebody is looking: the semantics, pausing in the background and offline, per-observer intervals, and testing it.
- [WebSocket & server-sent events · Undra docs](https://shreypdev.github.io/undra/docs/realtime.html): Real-time from the core: an opt-in WebSocket port with backpressure, server-sent events that resume, typed ends, reconnection under your control.
- [Local database · Undra docs](https://shreypdev.github.io/undra/docs/db.html): SQL in the core over the platform's SQLite: an opt-in Db port with migrations, bound parameters, transactions and typed errors.
- [Testing your app · Undra docs](https://shreypdev.github.io/undra/docs/testing.html): Preview and test your app on its real core with fakes and a manual clock, play a recorded session as a screen state, and replay port traffic.
- [Shipping an update · Undra docs](https://shreypdev.github.io/undra/docs/updates.html): Snapshots, cached queries and queued mutations across an app update: what migrates by name for free, how to write a hook, what is refused.
- [Reviewing generated code · Undra docs](https://shreypdev.github.io/undra/docs/reviewing-generated-code.html): Why generated bindings run to thousands of lines, how a pull request collapses them, and how to review and version a core's API as a schema diff.
- [Workers & crash recovery · Undra docs](https://shreypdev.github.io/undra/docs/web.html): The web core in a Web Worker: where synchronous ports run, the worker.ports module, and restarting a trapped wasm core from its last snapshot.
- [Operating in production · Undra docs](https://shreypdev.github.io/undra/docs/production.html): Crash reports that name the Rust frame, symbol files, background runs for the offline queue, the size of the shipped core, and debugging into Rust.
- [One core or several · Undra docs](https://shreypdev.github.io/undra/docs/several-cores.html): When an app should carry one Undra core and when several, how a core's namespace keeps them apart, and how to load two side by side.
- [One core, several hosts · Undra docs](https://shreypdev.github.io/undra/docs/hosts.html): One Rust core under native, React Native and web apps at once, what each host links, and how a React Native app moves to native screen by screen.
- [Bazel · Undra docs](https://shreypdev.github.io/undra/docs/bazel.html): Build an Undra core for every platform, generate its bindings and compile the code that uses them as Bazel targets: hermetic, offline and cached.
- [Cookbook · Undra docs](https://shreypdev.github.io/undra/docs/cookbook/): Recipes for what every app does: auth, paging, forms, uploads, real-time and offline-first, each a tested module, plus moving from KMP or UniFFI.
- [Auth · Undra cookbook](https://shreypdev.github.io/undra/docs/cookbook/auth.html): A session store, tokens in the secure store, one re-auth on a 401, and a logout that clears what the user left behind. Written once for three UIs.
- [Pagination · Undra cookbook](https://shreypdev.github.io/undra/docs/cookbook/pagination.html): A keyed list fed page by page, a view derived from it, the cursor in a signal, and a load-more that is safe to call on every frame.
- [Forms · Undra cookbook](https://shreypdev.github.io/undra/docs/cookbook/forms.html): A signal per field, the errors derived in the core, and a submit that refuses typed: validation written once for three UIs.
- [File upload · Undra cookbook](https://shreypdev.github.io/undra/docs/cookbook/upload.html): A file from the Fs port sent in parts over Http, progress as a signal, and retries through the offline queue, even across a restart.
- [Real-time · Undra cookbook](https://shreypdev.github.io/undra/docs/cookbook/realtime.html): A WebSocket that reconnects in the core with backoff on the Timer port, server-sent events as the fallback, and a typed end for every way it stops.
- [Live leaderboard · Undra cookbook](https://shreypdev.github.io/undra/docs/cookbook/leaderboard.html): Rank 100,000 players from a 1.4 MB snapshot and a delta stream: ingest on the blocking pool, publish a 780-byte window, hold the core lock for 375 ns.
- [Offline-first · Undra cookbook](https://shreypdev.github.io/undra/docs/cookbook/offline.html): Persisted queries, writes that queue and survive a restart, an outbox the UI can show, and an update that changes the data on the device.
- [Your network stack · Undra cookbook](https://shreypdev.github.io/undra/docs/cookbook/network-stack.html): Your OkHttpClient, URLSession or fetch behind the Http, WebSocket and Sse ports: its token refresh, interceptors and pinning apply to the core's requests.
- [Your own port · Undra cookbook](https://shreypdev.github.io/undra/docs/cookbook/custom-port.html): Your own port, declared once in Rust: Swift implements it from closures or a class (main-actor safe), Kotlin as an object, TypeScript as an object literal.
- [Moving from Kotlin Multiplatform · Undra cookbook](https://shreypdev.github.io/undra/docs/cookbook/from-kmp.html): Adopt Undra next to a Kotlin Multiplatform codebase in three steps: side by side, one feature, the whole domain, and what each step removes.
- [Moving from UniFFI · Undra cookbook](https://shreypdev.github.io/undra/docs/cookbook/from-uniffi.html): Move a Rust core from UniFFI to Undra in three steps, with what maps to what and what does not yet.
- [Supporting iOS 15 and 16 · Undra cookbook](https://shreypdev.github.io/undra/docs/cookbook/ios-15-16.html): Set the iOS deployment target below 17 and generated Swift stores become ObservableObjects: what changes in views, what degrades, how to raise the floor.
- [Sample app: Fieldbook · Undra docs](https://shreypdev.github.io/undra/docs/sample.html): Fieldbook, field notes with photos on one Rust core: auth, an offline queue, a derived notebook, an update with a hook, and live presence.
- [The CLI · Undra docs](https://shreypdev.github.io/undra/docs/cli.html): Every undra command and flag, the undra.toml project file, exit codes and how errors are reported.
- [Architecture · Undra docs](https://shreypdev.github.io/undra/docs/architecture.html): How Undra is built: the schema, generators, runtimes, wire format and C ABI, the threading model, diagnostics, and the twelve rules every change follows.
- [Error codes · Undra docs](https://shreypdev.github.io/undra/docs/errors.html): Every Undra diagnostic by code, from macros, schema validation, the runtime and the CLI: what triggers it, why, and the fix, with real messages.
- [API overview, Swift · Undra docs](https://shreypdev.github.io/undra/docs/api-swift.html): What Undra's generated Swift looks like: records, enums, errors, objects, stores, query handles and ports, and how the UndraRuntime package loads the core.
- [API overview, Kotlin · Undra docs](https://shreypdev.github.io/undra/docs/api-kotlin.html): What Undra's generated Kotlin looks like: data classes, sealed types, suspend functions, StateFlow-backed stores, query handles and ports.
- [API overview, TypeScript · Undra docs](https://shreypdev.github.io/undra/docs/api-typescript.html): What Undra's generated TypeScript looks like: interfaces, unions, error classes, promise-returning stores with signals, React hooks and adapters.

## Reference

- [Swift reference · Undra docs](https://shreypdev.github.io/undra/reference/swift.html): Every declaration Undra generates for Swift from the playground: types, errors, objects, stores, queries and ports, with their docs.
- [Kotlin reference · Undra docs](https://shreypdev.github.io/undra/reference/kotlin.html): Every declaration Undra generates for Kotlin from the playground: types, errors, objects, stores, queries and ports, with their docs.
- [TypeScript reference · Undra docs](https://shreypdev.github.io/undra/reference/typescript.html): Every declaration Undra generates for TypeScript from the playground: types, errors, objects, stores, queries and ports, with their docs.
- [Rust API reference](https://shreypdev.github.io/undra/reference/rust/undra/index.html): rustdoc for the undra crate and the runtime, signals, query, ports, wire and meta crates it re-exports

## Roadmap

- [Undra roadmap: shipped, next, later and exploring](https://shreypdev.github.io/undra/roadmap/): The Undra roadmap: what is in 1.0, 1.1 and 1.2, what is planned next and later, and what is only being explored. Updated with the project record.

## Blog

- [Undra 1.2: no drift between three hosts | Undra blog](https://shreypdev.github.io/undra/blog/undra-1-2-no-drift/): One core made three hosts agree on logic. 1.2 adds a diff of one flow recorded per platform, a custom port that compiles on iOS, and a faster gate.
- [Undra 1.0: one Rust core under native apps | Undra blog](https://shreypdev.github.io/undra/blog/undra-1-0/): What Undra is, who it is for, what is in 1.0, how to try it in five minutes, and what it is not.
- [Fifteen levers: the JavaScript runtime at 16 KB | Undra blog](https://shreypdev.github.io/undra/blog/the-javascript-runtime-at-16-kb/): How what a hello-world page loads up front of @undra/runtime went from 22,100 to 15,774 bytes gzipped without removing a feature.
- [A week of outside use: seven findings | Undra blog](https://shreypdev.github.io/undra/blog/a-week-of-outside-use/): A team tried Undra for a week and sent seven findings. Five are fixed, each with a decision record and a review; two were not taken on, and why.
- [Why Undra is the default choice | Undra blog](https://shreypdev.github.io/undra/blog/why-undra-is-the-default-choice/): A sourced matrix of what KMP, UniFFI, Flutter and React Native stop you doing, what Undra solved and how, what it costs to adopt, and what is still open.
- [Undra vs Kotlin Multiplatform for shared logic | Undra blog](https://shreypdev.github.io/undra/blog/undra-vs-kotlin-multiplatform/): Undra and Kotlin Multiplatform both share logic and keep the UI native. A dated, sourced comparison: iOS, web, reads, tooling, ecosystem and team fit.
- [Reads never cross the boundary: how Undra works | Undra blog](https://shreypdev.github.io/undra/blog/reads-never-cross-the-boundary/): How Undra mirrors Rust state into SwiftUI, Compose and React: change-sets, keyed lists as recorded operations, a schema-hash gate, and what it all costs.
- [Why Undra keeps your UI native | Undra blog](https://shreypdev.github.io/undra/blog/why-undra-keeps-your-ui-native/): Shared UI and shared logic are different bets. What Flutter, React Native and Compose Multiplatform trade, who should pick which, and where Undra stops.
- [Undra vs UniFFI and Crux: Rust under a native app | Undra](https://shreypdev.github.io/undra/blog/undra-vs-uniffi-and-crux/): Three ways to put a Rust core under SwiftUI, Compose and React: UniFFI bindings, Crux's Elm-style core, and Undra's mirrored state. Dated and sourced.

## Source and numbers

- [GitHub repository](https://github.com/shreypdev/undra): source, issues and releases
- [Specification](https://github.com/shreypdev/undra/blob/main/docs/SPEC.md): the binding implementation spec (wire format, ABI, schema)
- [Benchmark results](https://github.com/shreypdev/undra/blob/main/bench/RESULTS.md): host-measured numbers and budgets

## Optional

- [All documentation in one file](https://shreypdev.github.io/undra/llms-full.txt): every docs page, the roadmap and every post as Markdown
- [RSS feed](https://shreypdev.github.io/undra/feed.xml)