React Native SDK

Use @h1r-ai/croche-react-native for Croche’s project API on React Native.

0.5.0 package release pending verification. Confirm package availability before following the install command.

Requirements

• Node.js 22+ on macOS/Linux. Windows verification pending.
• React Native 0.76 or later, with the New Architecture.
• iOS 15.1 or later.
• Android API 26 or later.

Install

npm install @h1r-ai/croche@0.5.0 @h1r-ai/croche-react-native@0.5.0
cd ios && pod install

You do not need a Rust toolchain or a Croche source checkout.

Open your project

Import Croche from @h1r-ai/croche-react-native, not the TypeScript package’s default entry point. It exposes Croche.open(...), croche.agent(...), and the agent message APIs described in the TypeScript guide.

The React Native SDK manages app storage and secrets. Do not pass storage, secretStorage, or serverKey.

For simulators and emulators, pass the SDK debug key (cdt_) as debugKey. In the planned quickstart workflow, after the agent installs the CLI, you run croche login yourself and enter your developer key (dk_) at the hidden prompt, never in chat; your agent creates the project and has the CLI write CROCHE_DEBUG_KEY to a private .env file without displaying it. That CLI behavior remains pending release verification.

Neither .env nor process.env.CROCHE_DEBUG_KEY automatically populates a React Native bundle. The agent maps the private file’s value through your app’s existing debug-only build configuration into an app input such as developmentKey, then passes debugKey: __DEV__ ? developmentKey : undefined. Do not invent a loader import or add a dependency without permission; if no loader exists, resolve that build-wiring step rather than asking for the key in chat.

Fail locally when the debug-build value is missing, without displaying it, and rebuild the debug app after changing its configuration. Exclude the secret at build time from release artifacts; __DEV__ alone does not prove a bundled secret was removed. Keep it out of source control. The CLI’s account key never goes into debugKey, and login does not populate the app’s SDK key.

This package’s Croche.open(...) API can use Studio AI config. Debug keys follow drafts by default. A Studio config replaces the code config as a whole and applies on the next open after a sync; see app config and language before editing a draft.

Selected Croche.open options

Option	What your app supplies
projectKey	Your public project key
debugKey	A development-only key for simulator or emulator testing
user	The authenticated user’s stable ID
config	App instructions, agents, and tool declarations
config.model	The app’s model choice. Set it explicitly; see Models for recommendations, allowed IDs and default/fallback behavior.
handlers	App handlers keyed by tool name
language	The user’s language, as a BCP-47 tag. Selects config.languages.<tag> by exact tag first, then primary subtag; otherwise uses the base config as is. Automatic device-locale selection when omitted is pending 0.5.1 verification; do not rely on it in 0.5.0.
config.defaultLanguage	The base config’s authored language (default "en"), used only for config-layer selection; not the user’s language or a fallback for it
config.languages.<tag>	Translated config branch; without a match, the base config stays unchanged

When using 0.5.0, pass language explicitly rather than relying on automatic device-locale selection, which is pending 0.5.1 verification. An English-only config still serves a Korean user. The model is not told language; it replies in the language the user writes unless instructions say otherwise. See app config and language.

Before distributing your app

Configure app verification in Studio for the native platform. The SDK uses App Attest on iOS and Play Integrity on Android. Android configuration includes android: { cloudProjectNumber }, using the Google Cloud project linked in Play Console.

TODO verify: the complete first-turn example and app-verification walkthrough against the released 0.5.0 package. Simulator success does not verify a physical-device release build.

See project settings and balance, limits, and errors before moving from development to production.