Setup - React Native - Offline Protocol Docs

Prerequisites

Node.js 18.x or higher
React 18.x or 19.x
React Native or Expo
A package manager: npm or yarn

1. Install the SDK

Install the SDK and its peer dependencies:

npm install @offline-protocol/id-react-native

Or with Yarn:

yarn add @offline-protocol/id-react-native

2. Import the SDK

import { OfflineAppProvider } from "@offline-protocol/id-react-native";

3. Wrap your app with `OfflineAppProvider`

Pass your Project ID from the Offline Dashboard. The provider initializes the SDK, restores any saved session on launch, and makes auth state available to hooks throughout your app.

Expo Router

import { Stack } from "expo-router";
import { OfflineAppProvider } from "@offline-protocol/id-react-native";

const PROJECT_ID = "your-project-id-here";

export default function RootLayout() {
  return (
    <OfflineAppProvider projectId={PROJECT_ID}>
      <Stack />
    </OfflineAppProvider>
  );
}

React Native (App entry)

import { OfflineAppProvider } from "@offline-protocol/id-react-native";
import App from "./App";

const PROJECT_ID = "your-project-id-here";

export default function Root() {
  return (
    <OfflineAppProvider projectId={PROJECT_ID}>
      <App />
    </OfflineAppProvider>
  );
}

Optional: custom location provider

If you use proof-of-location features, pass a function that returns the device’s coordinates:

import * as Location from "expo-location";
import {
  OfflineAppProvider,
  type LocationProvider,
} from "@offline-protocol/id-react-native";

const locationProvider: LocationProvider = async () => {
  const { coords } = await Location.getCurrentPositionAsync({});
  return { lat: coords.latitude, lon: coords.longitude };
};

export default function RootLayout() {
  return (
    <OfflineAppProvider
      projectId={PROJECT_ID}
      locationProvider={locationProvider}
    >
      {/* app content */}
    </OfflineAppProvider>
  );
}

4. Verify your setup

Use the useAuth hook to read auth state. On launch, the SDK asynchronously restores a session from the stored token — check loading before treating user === null as logged out.

import { Text } from "react-native";
import { useAuth } from "@offline-protocol/id-react-native";

function TestComponent() {
  const { user, loading, sessionRestoreError } = useAuth();

  if (loading) {
    return <Text>Loading session…</Text>;
  }

  if (sessionRestoreError?.reason === "network") {
    return <Text>Offline — session will restore when connected</Text>;
  }

  return (
    <Text>
      SDK connected! User: {user?.email ?? "Not authenticated"}
    </Text>
  );
}

Session restore errors

When a stored token cannot be validated, sessionRestoreError is set with a typed reason:

Reason	Meaning	SDK behavior
`"network"`	DNS failure, timeout, or device offline	Token is kept; retry when online
`"unauthorized"`	Token expired or invalid (401/403)	Token is cleared
`"unknown"`	Server error or unexpected response	Token is kept

5. Implement user authentication

Call loginWithModal() to open the built-in login bottom sheet. It returns void — the modal handles email OTP verification and username registration internally.

import { TouchableOpacity, Text } from "react-native";
import { useAuth } from "@offline-protocol/id-react-native";

function LoginButton() {
  const { loginWithModal, user, logout } = useAuth();

  if (user) {
    return (
      <>
        <Text>Welcome, {user.email}!</Text>
        <TouchableOpacity onPress={logout}>
          <Text>Log out</Text>
        </TouchableOpacity>
      </>
    );
  }

  return (
    <TouchableOpacity onPress={loginWithModal}>
      <Text>Login with Offline ID</Text>
    </TouchableOpacity>
  );
}

export default LoginButton;

API reference

`OfflineAppProvider`

Prop	Type	Required	Description
`projectId`	`string`	Yes	Project ID from the Offline Dashboard
`locationProvider`	`LocationProvider`	No	Returns `{ lat, lon }` for proof-of-location
`children`	`ReactNode`	Yes	App content

`useAuth()`

Field	Type	Description
`user`	`UserAccount \| null`	Current authenticated user
`token`	`string \| null`	Bearer token for API requests
`loading`	`boolean`	`true` while session restore is in progress
`sessionRestoreError`	`SessionRestoreFailedError \| null`	Set when session restore fails
`loginWithModal`	`() => void`	Opens the built-in login bottom sheet
`logout`	`() => void`	Clears user, token, and stored auth token
`sendCode`	`(email: string) => Promise<boolean>`	Sends OTP to email
`verifyCode`	`(email: string, otp: string) => Promise<UserAccount \| null>`	Verifies OTP and signs in
`refreshUser`	`() => Promise<void>`	Re-fetches the current user from `/users/me`
`registerUsername`	`(username: string) => Promise<Profile \| null>`	Registers a username for the current user
`isUsernameAvailable`	`(username: string) => Promise<boolean>`	Checks username availability

Other hooks

import {
  useProfiles,
  useConnections,
  useProofOfLocation,
} from "@offline-protocol/id-react-native";

Hook	Purpose
`useProfiles()`	List, search, and count user profiles
`useConnections()`	Manage peer connections
`useProofOfLocation()`	Register location via proof-of-location

Getting started

Technical Specification

ID SDK

Mesh SDK

Examples & Tutorials

Proof of Location

Glossary

Support

Legal

Setup - React Native

Prerequisites

1. Install the SDK

2. Import the SDK

3. Wrap your app with `OfflineAppProvider`

Expo Router

React Native (App entry)

Optional: custom location provider

4. Verify your setup

Session restore errors

5. Implement user authentication

API reference

`OfflineAppProvider`

`useAuth()`

Other hooks

​Prerequisites

​1. Install the SDK

​2. Import the SDK

​3. Wrap your app with OfflineAppProvider

​Expo Router

​React Native (App entry)

​Optional: custom location provider

​4. Verify your setup

​Session restore errors

​5. Implement user authentication

​API reference

​OfflineAppProvider

​useAuth()

​Other hooks

Prerequisites

1. Install the SDK

2. Import the SDK

3. Wrap your app with `OfflineAppProvider`

Expo Router

React Native (App entry)

Optional: custom location provider

4. Verify your setup

Session restore errors

5. Implement user authentication

API reference

`OfflineAppProvider`

`useAuth()`

Other hooks