DEV Community

Cover image for Building Type-Safe Biometric Authentication for React Native with Nitro Modules
Yash Nandha
Yash Nandha

Posted on

Building Type-Safe Biometric Authentication for React Native with Nitro Modules

#reactnative #typescript #opensource #mobile

Biometric authentication has become a standard part of modern mobile applications.

Face ID, Touch ID, fingerprint authentication, and device credentials give users a convenient way to verify their identity before accessing sensitive functionality.

For React Native applications, implementing these flows still requires communication with native iOS and Android authentication APIs.

That was the motivation behind building react-native-nitro-biometrics, an open-source biometric authentication library for React Native powered by Nitro Modules.

In this article, I'll explain the design decisions behind the library, how the API works, and how it can be used in real-world React Native applications.

Why Build react-native-nitro-biometrics?

There are already biometric authentication libraries available for React Native.

The goal of this project wasn't simply to create another wrapper around native APIs.

I wanted to build a library around a few principles:

  • Simple API
  • Strong TypeScript support
  • Native platform authentication
  • React Native New Architecture support
  • iOS and Android support
  • Minimal developer setup
  • Reusable authentication APIs
  • Clear authentication results

The result is react-native-nitro-biometrics.

Why Nitro Modules?

Nitro Modules provide a modern approach for building native modules for React Native applications using the New Architecture.

For a library that needs to communicate with native platform APIs, this provides a clean way to expose native functionality through a TypeScript-facing API.

The architecture can be thought of as:

React Native / TypeScript
          ↓
react-native-nitro-biometrics
          ↓
       Nitro Modules
          ↓
 Native iOS / Android APIs
          ↓
Platform Authentication System
Enter fullscreen mode Exit fullscreen mode

The JavaScript API stays simple while the native implementation handles platform-specific authentication behavior.

Supported Authentication

The library supports common biometric authentication methods available on supported devices.

Authentication Platform
Face ID iOS
Touch ID iOS
Optic ID Supported Apple devices
Fingerprint Android
Face Android devices where supported
Iris Android devices where supported
Device credentials iOS / Android where supported

The exact authentication methods available depend on the device hardware, operating-system version, enrollment state, and platform capabilities.

Installation

Install the package with npm:

npm install react-native-nitro-biometrics react-native-nitro-modules
Enter fullscreen mode Exit fullscreen mode

Or with Yarn:

yarn add react-native-nitro-biometrics react-native-nitro-modules
Enter fullscreen mode Exit fullscreen mode

The library is designed for React Native applications using the New Architecture.

Basic Authentication

The main authentication API is intentionally simple.

import { authenticate } from 'react-native-nitro-biometrics';

const result = await authenticate({
  promptMessage: 'Authenticate to continue',
  allowDeviceCredentials: true,
});

if (result.success) {
  console.log('Authentication successful');
} else {
  console.log('Authentication failed');
}
Enter fullscreen mode Exit fullscreen mode

The application requests authentication and handles the result.

The native platform is responsible for presenting the appropriate authentication interface and performing the platform's authentication process.

Checking Authentication Availability

Before starting an authentication flow, an application may want to check whether authentication is available.

import {
  canAuthenticate,
  getBiometryType,
} from 'react-native-nitro-biometrics';

const status = await canAuthenticate();
const type = await getBiometryType();

console.log(status);
console.log(type);
Enter fullscreen mode Exit fullscreen mode

This can be useful when deciding whether to display a biometric login option.

For example:

Is biometric authentication available?
        |
        +---- No ----> Use another authentication method
        |
       Yes
        |
        v
Display biometric authentication
Enter fullscreen mode Exit fullscreen mode

Device Credential Fallback

Biometric authentication isn't always available.

A user may not have configured Face ID, Touch ID, fingerprint authentication, or another supported biometric method.

For supported platforms, the library can allow the device's credential mechanism as a fallback.

const result = await authenticate({
  promptMessage: 'Authenticate to continue',
  allowDeviceCredentials: true,
});
Enter fullscreen mode Exit fullscreen mode

This allows applications to build authentication flows that can work across a wider range of device configurations.

Real-World Use Cases

Biometric authentication can be useful in many different types of applications.

Secure Login

After a user has authenticated normally, biometrics can be used for subsequent access.

User opens application
        ↓
Biometric authentication
        ↓
Authentication successful
        ↓
Open application
Enter fullscreen mode Exit fullscreen mode

App Lock

Applications containing private or sensitive information can use biometric authentication when the application returns to the foreground.

Transaction Authorization

Financial and other sensitive applications can require additional authentication before performing an important action.

Create transaction
       ↓
Request biometric authentication
       ↓
Authentication successful
       ↓
Continue transaction
Enter fullscreen mode Exit fullscreen mode

Sensitive Settings

Biometric authentication can also be used before allowing users to access or modify security-sensitive settings.

Security Considerations

One important principle when working with biometric authentication is that an application generally should not need access to raw biometric data.

Instead, the application requests authentication through the platform's native authentication APIs.

The platform handles the authentication process and the application receives the resulting status.

Conceptually:

React Native Application
          |
          v
react-native-nitro-biometrics
          |
          v
Native Authentication API
          |
          v
iOS / Android Authentication System
          |
          v
Authentication Result
Enter fullscreen mode Exit fullscreen mode

react-native-nitro-biometrics does not require biometric images or biometric templates to perform its authentication flow.

As always, applications should still design their overall authentication and authorization architecture carefully. Successful local biometric authentication should not automatically be treated as a replacement for server-side authorization.

TypeScript

Another goal of the library is to provide a type-safe developer experience.

For example:

const result = await authenticate({
  promptMessage: 'Authenticate to continue',
  allowDeviceCredentials: true,
});
Enter fullscreen mode Exit fullscreen mode

Typed APIs make it easier to discover available options through TypeScript and IDE autocomplete.

This is particularly useful for libraries where configuration options and authentication results are part of the public API.

React Native New Architecture

The package is built around React Native's New Architecture and Nitro Modules.

This makes it suitable for modern React Native projects that are already using the New Architecture.

For native-module authors, this also provides an opportunity to design APIs specifically around modern React Native's native integration model rather than maintaining separate legacy and modern implementations.

Testing

The project includes Jest tests for the JavaScript and TypeScript API.

The test suite covers areas such as:

  • Exported biometric APIs
  • Authentication results
  • Biometry type detection
  • Sensor availability
  • Authentication failure handling
  • Hook initialization
  • Manual status checking
  • Hook authentication

The goal is to keep the JavaScript API predictable while the native implementations handle platform-specific authentication behavior.

Open Source

react-native-nitro-biometrics is open source and available on GitHub.

The project is still evolving, so feedback is especially useful around:

  • API design
  • iOS support
  • Android support
  • Error handling
  • Developer experience
  • Additional authentication use cases

If you're building React Native applications with the New Architecture, I'd be interested in hearing how you approach biometric authentication.

Try It

Install the package:

npm install react-native-nitro-biometrics
Enter fullscreen mode Exit fullscreen mode

GitHub

https://github.com/yashnandha/react-native-nitro-biometrics

npm

https://www.npmjs.com/package/react-native-nitro-biometrics

Conclusion

Biometric authentication is a relatively small feature from the user's perspective, but implementing it consistently across iOS and Android requires native platform integration.

With Nitro Modules, React Native developers can expose native functionality while keeping a clean TypeScript-facing API.

react-native-nitro-biometrics is my attempt to provide that experience for biometric authentication in modern React Native applications.

The project is open source, and contributions, issues, and feedback are welcome.

Top comments (0)