---
title: React Native SDK
description: Open a project and integrate Croche into your React Native app.
---

[!nav:main](/nav/main.md)

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

```sh
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](typescript.md).

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](../quickstart.md), 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](../concepts/config.md) 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](../models.md) 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](../concepts/config.md).

## 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](../studio/settings.md) and [balance, limits, and errors](../concepts/credits.md) before moving from development to production.