Registry / auth-security / react-native-keychain

react-native-keychain

JSON →
library10.0.0jsnpmunverified

react-native-keychain is a library providing secure access to platform-native credential storage on iOS (Keychain) and Android (Keystore). It enables React Native applications to securely store sensitive data such as passwords, authentication tokens, and other user credentials, protecting them from unauthorized access. The current stable version is 10.0.0, released in late 2024 / early 2025. The project has a consistent release cadence with multiple patch and minor versions preceding major updates, indicating active maintenance and feature development. Key differentiators include robust support for biometric authentication, integration with Android's Jetpack DataStore for enhanced security and performance, and optional iCloud synchronization for iOS keychain items. It explicitly supports modern React Native versions and provides TypeScript definitions.

npm install react-native-keychain
INSTALL
IMPORT
SIG · REACT-NATIVE-KEYCH
R
react-native-keychain
auth-securityjavascriptv10.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Keychain
import * as Keychain from 'react-native-keychain';
const Keychain = require('react-native-keychain');
Common pattern for accessing all module functions. The library ships with TypeScript types.
getGenericPassword
import { getGenericPassword } from 'react-native-keychain';
import getGenericPassword from 'react-native-keychain';
This is a named export, not a default export.
ACCESSIBLE
import { ACCESSIBLE, SECURITY_LEVEL } from 'react-native-keychain';
import { Accessible } from 'react-native-keychain';
Constants for configuring keychain item accessibility and security levels are named exports and typically uppercase.

Demonstrates how to store, retrieve, and reset generic credentials (username/password) using `react-native-keychain` with specific access control and security levels.

import * as Keychain from 'react-native-keychain'; async function storeAndRetrieveCredentials(username: string, password_input: string) { try { // Store the credentials await Keychain.setGenericPassword(username, password_input, { service: 'myAppService', accessControl: Keychain.ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY, securityLevel: Keychain.SECURITY_LEVEL.SECURE_SOFTWARE }); console.log('Credentials successfully stored!'); // Retrieve the credentials const credentials = await Keychain.getGenericPassword({ service: 'myAppService' }); if (credentials) { console.log('Credentials successfully loaded for user ' + credentials.username); console.log('Password is ' + credentials.password); // In a real app, you would use these credentials, not log the password directly. } else { console.log('No credentials stored.'); } // Example of resetting credentials await Keychain.resetGenericPassword({ service: 'myAppService' }); console.log('Credentials successfully reset!'); } catch (error) { console.error('Keychain operation failed', error); } } // Example usage: // Use environment variables or secure inputs in a real application const myUsername = process.env.KEYCHAIN_USERNAME ?? 'testuser'; const myPassword = process.env.KEYCHAIN_PASSWORD ?? 'supersecretpassword'; storeAndRetrieveCredentials(myUsername, myPassword);
Debug
Known issues
breakingVersion 10.0.0 introduces a breaking change requiring `minAndroidSdk` to be 23 or higher. Applications targeting older Android API levels will not build or function correctly.
fix
Update your `minAndroidSdk` in `android/app/build.gradle` to at least 23.
affects: >=10.0.0
breakingThe deprecated FacebookConceal integration and library warmup methods were removed in v10.0.0. If your application relied on these, they must be removed from your codebase.
fix
Remove any calls to `library warmup` as autolinking handles initialization. If using `FacebookConceal`, consider staying on an older version or migrating to a different encryption method.
affects: >=10.0.0
gotchaFor biometric authentication features (e.g., Face ID), iOS requires the `NSFaceIDUsageDescription` key in your `Info.plist` with a user-facing explanation of why the app needs Face ID access. Failure to include this will result in a runtime crash when attempting to use Face ID.
fix
Add `<key>NSFaceIDUsageDescription</key><string>Your privacy message here</string>` to your `ios/YourApp/Info.plist` file.
affects: >=1.0.0
gotchaOlder versions of `react-native-keychain` had compatibility issues with specific React Native versions (e.g., 0.69-0.71, 0.73), leading to build failures or unexpected behavior.
fix
Always ensure you are on the latest stable version of `react-native-keychain` to benefit from compatibility fixes with recent React Native releases. Check the changelog for specific version requirements.
affects: <9.2.3
deprecatedOn Android, `SharedPreferences` for storage was replaced by Jetpack `DataStore` in v9.2.0 for enhanced security and performance. While migration is seamless, be aware of the underlying change.
fix
No direct fix required for existing installations as migration is automatic, but new implementations should understand DataStore is the backend.
affects: >=9.2.0
Errors
Common errors & fixes
IllegalBlockSizeException on Android while decrypting
Occurred due to issues with encryption/decryption keys or data padding on Android.
fix
This issue was specifically addressed and fixed in `react-native-keychain` version 9.2.1. Upgrade to version 9.2.1 or newer.
Incompatibility between react-native-keychain Versions 8.2.0 and 9.0.0 for getGenericPassword
A specific incompatibility was introduced between these major versions affecting `getGenericPassword` calls.
fix
This issue was resolved in `react-native-keychain` version 9.2.3. Upgrade to version 9.2.3 or newer to fix the incompatibility.
Invariant Violation: `new NativeEventEmitter()` was called with a non-null argument but no `addListener` method was found on the passed-in native module.
Often indicates that the native module isn't correctly linked or initialized for the target platform, or an issue with React Native's native module bridge.
fix
Ensure `react-native link` (for older RN versions) or autolinking is working. Clean your project (e.g., `cd ios && pod cache clean --all && rm -rf build && pod install`), clear Metro cache (`npm start -- --reset-cache`), and rebuild the app.
Xcode Build Error: 'React/RCTBridgeModule.h' file not found
Common issue in iOS builds where CocoaPods dependencies are not correctly installed or linked, often after `react-native-keychain` installation.
fix
Navigate to your `ios` directory and run `pod install`. If issues persist, try `pod deintegrate && pod clean && pod install`, then clean the Xcode build folder.
Upgrade
Version history
10.0.0latest on npm
Audit
Dependencies
react-nativerequiredCore dependency for any React Native module.
Agent activity
25 hits · last 30 days
node
24
OpenAI (training)
1
Resources