Cryptographically Secure Random Bytes for React Native

1.0.1 · active · verified Sun Apr 19

The `react-native-securerandom` library provides a robust solution for generating cryptographically-secure random bytes within React Native applications. Currently stable at version `1.0.1`, it utilizes native platform APIs such as `SecRandomCopyBytes` on iOS, `SecureRandom` on Android, and `System.Security.Cryptography.RandomNumberGenerator` on Windows to ensure true cryptographic randomness, differentiating it from JavaScript-only PRNGs. Recent updates, including version `1.0.1`, address compatibility with newer React Native versions (e.g., Gradle 7 support for RN 0.68+) and have seen new maintainers join the project, indicating ongoing but generally slower maintenance focused on compatibility and stability rather than rapid feature additions.

Common errors

```
Invariant Violation: Native module RNSecureRandom is not available. Did you forget to link the native module?
```
cause The native module for `react-native-securerandom` was not correctly linked during the build process, or auto-linking failed.

fix Ensure the package is properly linked. If `react-native link` doesn't work, follow the 'Manual linking' instructions in the README for your specific platform (iOS, Android, Windows).
```
Execution failed for task ':app:processDebugMainManifest'. > com.android.builder.internal.aapt.AaptException: AAPT2 error: check logs for details
```
cause A generic Android build error, often related to `react-native-securerandom` not being correctly integrated into the Android project's Gradle files.

fix Verify that `android/settings.gradle` and `android/app/build.gradle` have the correct entries for `react-native-securerandom` as specified in the README's manual linking section.
```
Cannot find name 'generateSecureRandom'. Did you mean to import it from 'react-native-securerandom'?
```
cause Incorrect import statement or missing type declaration for `generateSecureRandom` in a TypeScript project.

fix Use the named import: `import { generateSecureRandom } from 'react-native-securerandom';` Ensure your TypeScript configuration correctly includes `node_modules` types.

Warnings

breaking Error handling for improper native module linking changed from synchronously throwing an error to returning a rejected Promise.
Fix: Update error handling logic to `await` the `generateSecureRandom` call and `catch` rejected Promises instead of using `try...catch` for synchronous errors.
breaking Android devices prior to API 19 (Android < 4.4) using versions `<=0.3.0` may have suffered from insufficient entropy, leading to less secure random number generation.
Fix: Upgrade to `react-native-securerandom@0.3.1` or higher to ensure the Google-provided security patch for Android entropy issues is applied.
gotcha Projects using React Native 0.68+ (which utilizes Gradle 7) may encounter Android build errors due to older Gradle compatibility issues.
Fix: Upgrade to `react-native-securerandom@1.0.1` or higher, which includes explicit support for Gradle 7.
gotcha Automatic linking (`react-native link`) might fail or require extensive manual configuration, especially for iOS Cocoapods or Android project setups, or in managed Expo workflows (which do not support native modules).
Fix: Refer to the 'Manual linking' section in the README for detailed platform-specific instructions. For Expo managed workflows, you must eject to a bare workflow to use this native module.
gotcha Older versions (pre-1.0.0) might experience issues with Cocoapods due to the podspec not being in the project root, affecting auto-detection.
Fix: Upgrade to `react-native-securerandom@1.0.0` or higher to benefit from the corrected podspec location for smoother Cocoapods integration.

Install

npm install react-native-securerandom npm
yarn add react-native-securerandom yarn
pnpm add react-native-securerandom pnpm

Imports

generateSecureRandom
wrong:
```
const generateSecureRandom = require('react-native-securerandom');
```
correct:
```
import { generateSecureRandom } from 'react-native-securerandom';
```
The library primarily uses named exports and is designed for modern ESM environments within React Native. Direct CommonJS `require` might not resolve correctly or provide proper TypeScript types.
generateSecureRandom (Promise usage)
wrong:
```
import { generateSecureRandom } from 'react-native-securerandom';

const randomBytes = generateSecureRandom(16); // Missing await
```
correct:
```
import { generateSecureRandom } from 'react-native-securerandom';

await generateSecureRandom(16);
```
`generateSecureRandom` returns a Promise and must be awaited or handled with `.then()` to access the generated bytes. Since v0.3.0, errors for improper linking also reject the Promise instead of throwing synchronously.
TypeScript types
```
import { generateSecureRandom, type SecureRandomError } from 'react-native-securerandom';
```
The package ships with TypeScript type definitions, providing type safety for `generateSecureRandom` and potential error types like `SecureRandomError` (though `SecureRandomError` itself is not explicitly exported in the current README, it's good practice to mention custom error types if they existed).

Quickstart

Demonstrates how to import `generateSecureRandom` and asynchronously use it to generate an array of cryptographically secure random bytes, including basic error handling.

import { generateSecureRandom } from 'react-native-securerandom';

async function getRandomBytes(length: number): Promise<Uint8Array> {
  try {
    const randomBytes = await generateSecureRandom(length);
    console.log(`Generated ${length} secure random bytes:`, randomBytes);
    return randomBytes;
  } catch (error) {
    console.error('Failed to generate secure random bytes:', error);
    throw error;
  }
}

// Example usage:
getRandomBytes(12).then(bytes => console.log('First batch done.'));
getRandomBytes(32).then(bytes => console.log('Second batch done.'));

view raw JSON →