npm package: @futureverse/auth-react-native
Description: Provides React Native authentication components and providers for [Futureverse Auth](https://www.npmjs.com/package/@futureverse/auth). This library enables seamless Pass authentication integration in React Native and Expo applications.
Latest version: 1.1.2

# Futureverse Auth React Native

Provides React Native authentication components and providers for [Futureverse Auth](https://www.npmjs.com/package/@futureverse/auth). This library enables seamless Pass authentication integration in React Native and Expo applications.

## Installation

This library supports Expo SDK 52:

```bash
npx create-expo-app my-app-name --template default@sdk-52
```

Install the package:

```bash
npm install @futureverse/auth-react-native
```

Required dependencies:

```bash
npm install @tanstack/react-query viem react-native-svg react-native-quick-crypto @walletconnect/react-native-compat react-native-get-random-values @react-native-async-storage/async-storage @react-native-community/netinfo react-native-keychain react-native-inappbrowser-reborn
```

If using android, install:

```bash
npm install expo-gradle-ext-vars
```

Then update your `app.json` file to ensure compatible in-app browser versions:

```json
"plugins": [ ["expo-gradle-ext-vars", { "androidXBrowser": "1.6.0" }] ] }
```

## Basic Usage

### Setup Web3 Config

```typescript
// config/wagmiUtils.ts

import { CreateConfigParameters } from 'wagmi';

import { arbitrum, mainnet, polygon, avalanche, bsc, optimism, gnosis, zkSync, zora, base, celo, aurora, sepolia } from '@wagmi/core/chains';

export const chains: CreateConfigParameters['chains'] = [mainnet, polygon, avalanche, arbitrum, bsc, optimism, gnosis, zkSync, zora, base, celo, aurora, sepolia];
```

```typescript
// config/web3Config.ts

import { mainnet } from '@wagmi/core/chains';
import { defaultWagmiConfig } from '@reown/appkit-wagmi-react-native';
import { AppKitOptions } from '@reown/appkit-wagmi-react-native/lib/typescript/client';
import { supportedWallets, setupAppKit } from '@futureverse/auth-react-native';
import { chains } from './wagmiUtils';

export let appKitOptions: AppKitOptions;

export function configWeb3() {
  configAppKit();
  setupAppKit(appKitOptions);
}

function configAppKit() {
  const metadata = {
    name: 'wagmi-project-name',
    description: 'wagmi-project-description',
    url: 'project-url',
    icons: ['wagmi-project-icon'],
    redirect: {
      native: 'wagmi-project-native-redirect',
      universal: 'wagmi-project-universal-redirect',
      linkMode: true,
    },
  };

  const wagmiConfig = defaultWagmiConfig({
    chains,
    projectId: 'wagmi-project-id',
    metadata,
  });

  appKitOptions = {
    projectId: 'wagmi-project-id',
    wagmiConfig,
    featuredWalletIds: [supportedWallets.metamask], // Optional
    defaultChain: mainnet, // Optional
    enableAnalytics: false, // Optional - defaults to your Cloud configuration,
    metadata,
  };
}
```

### Setup Providers

```typescript
import React from 'react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { AuthReactNativeClient, AuthUiProvider, DefaultTheme } from '@futureverse/auth-react-native';
import { appKitOptions, configWeb3 } from '@/config/web3config';

configWeb3(); // configure web3 before creating and using auth client

const queryClient = new QueryClient();

const authClient = new AuthReactNativeClient({
  clientId: 'your-futureverse-client-id',
  postSignInredirectUri: 'your-app-redirect-uri',
  authorizationURL: 'your-authorization-url',
  hostWeb3SigningDomain: '',
});

const themeConfig = {
  colors: {
    ...DefaultTheme.colors,
    primaryBackground: '#000000',
  },
};

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <AuthUiProvider
        themeConfig={themeConfig}
        authClient={authClient}
        appKitOptions={appKitOptions} // Optional for wallet connections
      >
        {/* Your app components */}
      </AuthUiProvider>
    </QueryClientProvider>
  );
}
```

### Using Auth Hooks

```typescript
import React from 'react';
import { View, Button, Text } from 'react-native';
import { useAuth, useAuthUi } from '@futureverse/auth-react-native';

export default function HomeScreen() {
  const { openLogin } = useAuthUi();
  const { authClient, userSession } = useAuth();

  const handleLogin = () => {
    openLogin();
  };

  const handleLogout = async () => {
    await authClient.signOut();
  };

  return (
    <View>
      {userSession ? (
        <>
          <Text>Welcome! User ID: {userSession.user?.id_token}</Text>
          <Button title="Logout" onPress={handleLogout} />
        </>
      ) : (
        <Button title="Login" onPress={handleLogin} />
      )}
    </View>
  );
}
```

## API Reference

### AuthClient

Main authentication client for React Native applications.

```typescript
const authClient = new AuthReactNativeClient({
  clientId: string;
  postSignInredirectUri: string;
  authorizationURL: string;
  hostWeb3SigningDomain: string;
});
```

### Providers

- **AuthUiProvider**: Main provider with built-in authentication UI
- **AuthThemeProvider**: Theme customization provider

### Hooks

- **useAuth()**: Access authentication state and client
- **useAuthUi()**: Control login modal state

### Theme Configuration

Optionally customize the authentication UI:

```typescript
import { DefaultTheme } from '@futureverse/auth-react-native';

const customTheme = {
  ...DefaultTheme,
  colors: {
    ...DefaultTheme.colors,
    primaryBackground: '#your-color',
  },
  images: {
    ...DefaultTheme.images,
    logo: require('path-to-your-logo.png'), // replace default auth UI title with logo (png/jpg)
  },
};
```

## Storage

The library uses secure storage by default:

- **iOS**: Keychain
- **Android**: Keystore

## Related Packages

- [@futureverse/auth](https://www.npmjs.com/package/@futureverse/auth) - Core authentication library