# Install for React Native

> Install the stable Nosmai Effects SDK for React Native in a New Architecture project and configure its native dependencies for physical ARM64 devices.

> For AI agents: the complete documentation index is at https://nosmai.com/llms/effects.txt

Product: Nosmai Effects
Group: get-started
Source: https://nosmai.com/docs/effects/installation/react-native/

## Prerequisites

- React Native `0.81.5` with React `19.1.x`, or Expo SDK 54
- New Architecture enabled
- Node 20.19.4 or later
- A physical arm64 iOS or `arm64-v8a` Android device
- Android API 24 or later for the React Native host
- iOS 15 or later
- A [Nosmai licence key](/docs/effects/license-key/) for each native identity
- The verified Android AAR and iOS CocoaPod used by the package

The React Native package is public on npm under the `latest` tag. Expo Go cannot
load its TurboModule or Fabric component, so Expo projects require a custom
development or release build.

## Add the package

Install the current stable release from npm:

```sh
yarn add @nosmai/react-native-effects-sdk
```

Use the exact version when the application must stay on this qualified release:

```sh
yarn add @nosmai/react-native-effects-sdk@1.0.0
```

Commit the resulting lockfile. Do not depend on an unpinned moving Git branch
in a production application.

## Configure a bare React Native Android app

Download and verify the Android `3.0.4` AAR. Put exactly one copy here:

[Download the verified Android v3.0.4 release](https://github.com/nosmai/nosmai_effects_sdk_android/releases/tag/v3.0.4).

```text
android/app/libs/nosmai-release.aar
```

Configure the app module:

```gradle
android {
  defaultConfig {
    minSdkVersion 24
    ndk {
      abiFilters 'arm64-v8a'
    }
  }
}

dependencies {
  implementation files('libs/nosmai-release.aar')
}
```

Keep New Architecture enabled in `android/gradle.properties`:

```properties
newArchEnabled=true
```

The library manifest declares camera, internet, recording audio, and the legacy
write permission limited to API 28. The host app still requests camera and
microphone permission at runtime.

## Configure a bare React Native iOS app

The package pod depends on `NosmaiCameraSDK ~> 3.0.4` and resolves the verified
native SDK `3.0.4` framework. It does not vendor a framework.

Add these keys to the host application's `Info.plist`:

```xml
<key>NSCameraUsageDescription</key>
<string>This app uses the camera for real-time filters and effects.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app uses the microphone when recording video.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>This app saves captured photos and videos to your library.</string>
```

Install pods:

```sh
cd ios
bundle exec pod install
cd ..
```

The iOS framework is device-only. Select a physical arm64 iPhone for runtime
verification.

## Configure Expo SDK 54

Keep the proprietary Android AAR outside the generated `android` directory, for
example at `vendor/nosmai-release.aar`. Add the config plugin:

```js
export default {
  expo: {
    newArchEnabled: true,
    plugins: [
      [
        '@nosmai/react-native-effects-sdk',
        {
          androidAarPath: './vendor/nosmai-release.aar',
          androidAarSha256: process.env.NOSMAI_ANDROID_AAR_SHA256,
          cameraPermission:
            'Allow this app to use the camera for Nosmai effects.',
          microphonePermission:
            'Allow this app to use the microphone when recording video.',
          photoLibraryAddPermission:
            'Allow this app to save captured photos and videos.',
        },
      ],
    ],
  },
};
```

Create a custom development build:

```sh
npx expo install expo-dev-client
npx expo prebuild --clean
npx expo run:android
```

For iOS, use a physical device:

```sh
npx expo run:ios --device
```

`expo prebuild --clean` recreates native directories. Keep the source AAR in a
stable vendor location and preserve unrelated manual native changes before
running it.

## Package size

The `1.0.0` npm package is about 226.1 kB packed and 1.1 MB unpacked. It contains
JavaScript, TypeScript declarations, the Fabric view, native bridges, and an
Expo config plugin. It excludes the proprietary Android AAR and iOS framework.
Native size impact therefore follows the Android and iOS artifacts rather than
the JavaScript archive alone.

## Verify it worked

Run the package and TypeScript checks in the host app, then build a native target:

```sh
yarn typecheck
yarn android
```

or build iOS from the workspace for a physical device. Confirm that importing
both symbols compiles:

```tsx
import {
  NosmaiCameraSdk,
  NosmaiCameraView,
} from '@nosmai/react-native-effects-sdk';
```

Continue to the [React Native quickstart](/docs/effects/quickstart/react-native/)
to request permission, mount the Fabric view, initialize, and start processing.

## Common errors

| Error | Cause | Fix |
| --- | --- | --- |
| `Cannot find native module 'NosmaiCameraSdk'` | App is running in Expo Go or native code was not rebuilt | Use an Expo development build or rebuild the bare native application |
| `E_NOT_INITIALIZED` | A camera or effect method ran before initialization | Await `NosmaiCameraSdk.initialize` before starting processing |
| `E_NO_PREVIEW` | The Fabric view was not mounted before processing started | Mount `NosmaiCameraView`, wait for layout, then call `startProcessing` |
| `E_CAMERA_PERMISSION` | Android host did not grant runtime camera access | Request `PermissionsAndroid.PERMISSIONS.CAMERA` before startup |
| `INSTALL_FAILED_NO_MATCHING_ABIS` | Android target lacks `arm64-v8a` | Use a physical ARM64 device and keep the ABI filter |
| `building for iOS Simulator, but linking in object file built for iOS` | Simulator was selected | Run the native build on a physical iPhone |

## Next steps

- [Add real-time camera effects to a React Native app](/docs/effects/quickstart/react-native/)
- [Get and apply a licence key](/docs/effects/license-key/)
- [Control a camera game in React Native](/docs/effects/guides/effects/control-a-camera-game/react-native/)
- [Check React Native capabilities](/docs/effects/platform-support/)
- [Apply a beauty filter in React Native](/docs/effects/guides/effects/apply-a-beauty-filter/react-native/)

## References

- [React Native package on npm](https://www.npmjs.com/package/@nosmai/react-native-effects-sdk)
- [React Native repository](https://github.com/nosmai/nosmai_effects_sdk_react_native)
- [Android native releases](https://github.com/nosmai/nosmai_effects_sdk_android/releases/latest)
- [Nosmai Effects](https://nosmai.com/effects/)