Installation & prerequisites

Private npm access

Both packages are published to npm as restricted packages under the @optimalai scope with a beta dist-tag. They are not public and there is no latest tag yet.

1. Ask OptimalAI to add your npm username to the sdk-beta-readers team. That team has read-only access to @optimalai/react-native and @optimalai/model-tools and nothing else.
2. Create your own granular, read-only npm token. Each customer owns their own token — never share one across teams.
3. Copy .npmrc.example to .npmrc. The file must contain only the variable reference, never the literal token:

@optimalai:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

4. Provide the token through the environment locally, and as a secret named NPM_TOKEN in CI and EAS Build:

export NPM_TOKEN="your-read-only-token"

Never commit the token

.npmrc references ${NPM_TOKEN} so the file itself is safe to commit. The token belongs in your shell environment, your CI secret store, or your EAS secret — nowhere else.

Platform baseline

Requirement	Minimum
Expo SDK	57
React Native	0.86 (New Architecture)
iOS	16.4
Android	API 24
Xcode	26.4

The Old Architecture is not supported.

Install the packages

npx expo install @optimalai/react-native@beta
npx @optimalai/model-tools@beta add kokoro-82m-v1.1-zh-int8

@optimalai/react-native is the runtime library your app links against. @optimalai/model-tools is a development-time CLI — it does not ship in your bundle, but it produces the optimalai-models.ts module your app imports.

Development Builds only

This SDK includes native code (ONNX Runtime). Expo Go ships a fixed set of native modules and cannot load it, so you must build a Development Build:

npx expo run:ios
# or
npx expo run:android

Any time you change native dependencies, rebuild. A JS-only reload is not enough.

Desktop smoke test

Before you touch a device, pnpm model:smoke in the SDK repository runs the model through a desktop ONNX Runtime as a sanity check. It does not replace on-device acceptance testing.

Next

• Expo & Metro setup
• Model preparation