{"id":11777,"library":"react-native-keychain","title":"React Native Keychain Access","description":"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.","status":"active","version":"10.0.0","language":"javascript","source_language":"en","source_url":"git://github.com/oblador/react-native-keychain","tags":["javascript","react-native","react-component","react-native-component","react","mobile","ios","android","keychain","typescript"],"install":[{"cmd":"npm install react-native-keychain","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-keychain","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-keychain","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for any React Native module.","package":"react-native","optional":false}],"imports":[{"note":"Common pattern for accessing all module functions. The library ships with TypeScript types.","wrong":"const Keychain = require('react-native-keychain');","symbol":"Keychain","correct":"import * as Keychain from 'react-native-keychain';"},{"note":"This is a named export, not a default export.","wrong":"import getGenericPassword from 'react-native-keychain';","symbol":"getGenericPassword","correct":"import { getGenericPassword } from 'react-native-keychain';"},{"note":"Constants for configuring keychain item accessibility and security levels are named exports and typically uppercase.","wrong":"import { Accessible } from 'react-native-keychain';","symbol":"ACCESSIBLE","correct":"import { ACCESSIBLE, SECURITY_LEVEL } from 'react-native-keychain';"}],"quickstart":{"code":"import * as Keychain from 'react-native-keychain';\n\nasync function storeAndRetrieveCredentials(username: string, password_input: string) {\n  try {\n    // Store the credentials\n    await Keychain.setGenericPassword(username, password_input, {\n      service: 'myAppService',\n      accessControl: Keychain.ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY,\n      securityLevel: Keychain.SECURITY_LEVEL.SECURE_SOFTWARE\n    });\n    console.log('Credentials successfully stored!');\n\n    // Retrieve the credentials\n    const credentials = await Keychain.getGenericPassword({\n      service: 'myAppService'\n    });\n\n    if (credentials) {\n      console.log('Credentials successfully loaded for user ' + credentials.username);\n      console.log('Password is ' + credentials.password);\n      // In a real app, you would use these credentials, not log the password directly.\n    } else {\n      console.log('No credentials stored.');\n    }\n\n    // Example of resetting credentials\n    await Keychain.resetGenericPassword({ service: 'myAppService' });\n    console.log('Credentials successfully reset!');\n\n  } catch (error) {\n    console.error('Keychain operation failed', error);\n  }\n}\n\n// Example usage:\n// Use environment variables or secure inputs in a real application\nconst myUsername = process.env.KEYCHAIN_USERNAME ?? 'testuser';\nconst myPassword = process.env.KEYCHAIN_PASSWORD ?? 'supersecretpassword';\n\nstoreAndRetrieveCredentials(myUsername, myPassword);","lang":"typescript","description":"Demonstrates how to store, retrieve, and reset generic credentials (username/password) using `react-native-keychain` with specific access control and security levels."},"warnings":[{"fix":"Update your `minAndroidSdk` in `android/app/build.gradle` to at least 23.","message":"Version 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.","severity":"breaking","affected_versions":">=10.0.0"},{"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.","message":"The 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.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Add `<key>NSFaceIDUsageDescription</key><string>Your privacy message here</string>` to your `ios/YourApp/Info.plist` file.","message":"For 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Older 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.","severity":"gotcha","affected_versions":"<9.2.3"},{"fix":"No direct fix required for existing installations as migration is automatic, but new implementations should understand DataStore is the backend.","message":"On 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.","severity":"deprecated","affected_versions":">=9.2.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"This issue was specifically addressed and fixed in `react-native-keychain` version 9.2.1. Upgrade to version 9.2.1 or newer.","cause":"Occurred due to issues with encryption/decryption keys or data padding on Android.","error":"IllegalBlockSizeException on Android while decrypting"},{"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.","cause":"A specific incompatibility was introduced between these major versions affecting `getGenericPassword` calls.","error":"Incompatibility between react-native-keychain Versions 8.2.0 and 9.0.0 for getGenericPassword"},{"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.","cause":"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.","error":"Invariant Violation: `new NativeEventEmitter()` was called with a non-null argument but no `addListener` method was found on the passed-in native module."},{"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.","cause":"Common issue in iOS builds where CocoaPods dependencies are not correctly installed or linked, often after `react-native-keychain` installation.","error":"Xcode Build Error: 'React/RCTBridgeModule.h' file not found"}],"ecosystem":"npm"}