Guides

Kuito turns TypeScript, TSX and CSS into native iOS and Android interfaces. Use it to build screens with native controls, reactive state and device APIs. It is experimental: APIs and generated projects may change.

Build a small native screen, run it on a simulator, and edit it while it is running. Kuito is experimental and not production-ready.

Compose native views with TSX. Start with a stack for layout, add text and controls, then connect them to state. Use this guide when building a screen or extracting a reusable component.

Use signal for a value that changes, computed for a value calculated from other state, and store for an object or array with independently changing fields. JSX reads subscribe to those values; a component's setup does…

Use lifecycle helpers for subscriptions, timers and native work that should exist only while a component is mounted. Create them during component setup.

Kuito provides platform-backed Web APIs without a browser DOM. Use fetch for HTTP, WebSocket for a persistent connection, and the available standard utilities for URLs, bytes and timing.

Use resource to load when a component mounts. Use task for work triggered by the user, such as saving a form. Both expose running, data and error signals, and cancel work when their component is disposed.

Use a virtualized List for growing data, stable item keys for row identity, and a guarded task for page requests. Refresh replaces the first page; reaching the end appends the next page.

Write notes locally before contacting the server so editing works offline. Mark acknowledged versions as synced without overwriting a newer local edit.

Use bundled images for app artwork, remote images for server content, and Symbol for platform icons. Put files your app owns in its assets directory.

Use a custom font for branding or typography. Bundle fonts needed on the first screen; load optional fonts when their content is requested.

Use List for content that needs native cell recycling. Use Scroll with For when a small set of children can all stay mounted.

Use TextField bindings, scroll-view avoidance and keyboard signals to keep editing comfortable. Start with native avoidance before adding custom motion.

Use native semantics, clear labels and scalable text so a screen works with screen readers and different input methods. Treat accessibility as part of each component’s behavior.

Use message catalogs for visible text and logical layout properties for spacing. This lets the same screen follow both the user's language and its reading direction.

Set launch artwork in configuration, then let it hand off to your first screen. Hold it only for work required before the app can display useful content.

Use event props for actions reported by a view. Use bound signals for controls whose value should stay synchronized with app state.

Use a ref for an imperative action on a mounted view. Prefer props and signals for the state a view displays.

Use this pattern for a password form with autofill, keyboard submission, a pending state and a session token stored in the platform keychain. Replace the endpoint with your authentication service.

Use format to display grouped digits while preserving native input behavior. Use the field's selection to insert clipboard text at the current caret or replace the selected range.

Bind controls to persisted signals when a preference should survive relaunch. Give each preference a stable key and validate stored data with a Standard Schema implementation.

Combine message catalogs, logical spacing and flexible layout for a badge that works in multiple languages. This example formats an unread count in English or Arabic and follows the locale's text direction.

Bind a Pager to a page signal for discrete navigation, and use scrollMotion for visuals that follow the finger between pages.

An app declares its routes one of two ways, and kuito create --routes files|components starts it on either. With file routes, the default, each file in app/ is a route that exports its screen. With component routes,…

Give each tab its own routes, then declare a modal alongside the tab container. Typed destinations let links and header actions share route definitions.

Use motion values for continuously changing UI properties, and signals for application state. Native gestures and animations can update views on the UI thread without waiting for JavaScript.

Kuito places motion-dependent props and gesture callbacks on the UI thread when it can prove they are safe there. Use the placement report to check a drag, scroll effect or animation that stutters or lags behind input.

Connect a scroll offset to visual properties when a header should move more slowly than the content. Motion bindings keep the effect synchronized with native scrolling.

Use gesture composition when the same card needs a continuous drag and a directional dismissal. The example exposes the same Keep/Pass actions through a native context menu.

Use the system picker when the user should choose an existing photo. Upload its local URI directly and display progress and errors. The system photo picker does not require broad photo-library permission.

Local notifications are one-shot requests. To offer a daily reminder, schedule a bounded set of future dates and replenish it when the app opens. An optional background task can also replenish them, but its timing is…

Use a native module to expose a platform SDK, hardware feature or native view to TypeScript. A module has one TypeScript spec plus Swift and Kotlin implementations. The spec generates the types and link table; an app…

Package a native module when several apps need the same platform integration. First implement and test it inside one app, following write a native module.

Use the development menu to inspect a running app, reload it, or diagnose a lost connection. Start the app with kuito dev ios or kuito dev android; these tools are available in development builds.

LogBox displays development warnings and errors on the device and maps stack frames back to your source. Use it when a tap fails, a promise rejects, or a Live Patch cannot run.

Start with the interaction that feels slow: opening a sheet, scrolling a feed, switching tabs or changing one value. Use the device monitor to locate the work, then a repeatable test to prevent regressions.

Use kuito/tests to render app components on the headless host, interact with them and assert user-visible behavior. No simulator or platform SDK is needed for these tests.

Use a phone to test camera input, permissions, haptics and real frame timing. kuito dev builds the native shell, installs it and sends code changes while it runs.

Use kuito build <platform> --profile release to produce a signed store artifact. Use --device when testing a release build on a specific phone or simulator.

Release builds record JavaScript errors and supported native failures on the device. Use a report and the matching source maps to find the original source location. Debug builds use LogBox instead and do not record…

Use an over-the-air update for a TypeScript or CSS fix compatible with an installed release shell. Updates replace bytecode on the next launch. Native code, modules, permissions, assets, fonts and database migrations…

Thank you for helping improve Kuito. The project is experimental: the most useful contributions are small, tested and clearly documented.