react-native-nitro-glasses

React Native SDK for Meta glasses and Meta Wearables workflows, built with Nitro Modules.

Use it for typed availability checks, permissions, paired-device discovery, connection lifecycle, camera preview streams, snapshots, photo and video media, display commands, event subscriptions, diagnostics, and deterministic mock testing from the same public API.

Install

bun add react-native-nitro-glasses react-native-nitro-modules

For Expo development builds:

bunx expo install react-native-nitro-glasses react-native-nitro-modules
bunx expo prebuild

Expo Go cannot load Nitro native modules. Use an Expo development build or a bare React Native app.

Expo Config

Add the config plugin before prebuilding:

export default {
  expo: {
    plugins: [
      [
        "react-native-nitro-glasses",
        {
          configureAndroidRepository: true,
        },
      ],
    ],
  },
};

Plugin options:

| Option | Default | What it does | | -------------------------------- | ------------------------------- | ---------------------------------------------- | | cameraPermission | Meta glasses camera message | Sets NSCameraUsageDescription. | | microphonePermission | Meta glasses microphone message | Sets NSMicrophoneUsageDescription. | | bluetoothPermission | Meta glasses Bluetooth message | Sets NSBluetoothAlwaysUsageDescription. | | configureAndroidRepository | true | Adds the Meta Wearables DAT Maven repository. | | androidRepositoryTokenProperty | metaWearablesToken | Gradle property name for the repository token. |

The plugin also adds Android camera, microphone, Bluetooth, Bluetooth scan, and Bluetooth connect permissions. Set configureAndroidRepository: false when your app manages the Meta Wearables repository itself or only uses mock mode.

Quick Start

import { useCallback, useState } from "react";
import {
  GlassesCameraView,
  MetaGlasses,
  useMetaGlasses,
  type GlassesCameraStream,
} from "react-native-nitro-glasses";

MetaGlasses.configure({ mode: "mock", mockDeviceCount: 1 });

export function GlassesScreen() {
  const { devices, requestPermissions, connect } = useMetaGlasses();
  const [stream, setStream] = useState<GlassesCameraStream>();

  const connectFirstDevice = useCallback(async () => {
    const [firstDevice] = devices;

    if (!firstDevice) {
      throw new Error("No paired glasses found");
    }

    await requestPermissions();
    const device = await connect(firstDevice.id);
    await device.startSession();

    const nextStream = await device.createCameraStream({ preferredFps: 30 });
    await nextStream.startPreview();
    setStream(nextStream);
  }, [connect, devices, requestPermissions]);

  return <GlassesCameraView streamId={stream?.id} />;
}

Public API

MetaGlasses

MetaGlasses.configure(options);
MetaGlasses.isAvailable();
MetaGlasses.getStatus();
MetaGlasses.getPermissions();
MetaGlasses.requestPermissions(["camera", "microphone", "bluetooth"]);
MetaGlasses.getPairedDevices();
MetaGlasses.connect(deviceId);
MetaGlasses.disconnect(deviceId);
MetaGlasses.getDiagnostics();
MetaGlasses.addListener((event) => {});
MetaGlasses.useMockMode(true);

useMetaGlasses()

Returns the current status, paired devices, diagnostics, and stable callbacks:

const {
  status,
  devices,
  diagnostics,
  refresh,
  requestPermissions,
  connect,
} = useMetaGlasses();

useMetaGlasses() avoids redundant React state updates when the native snapshot has not changed, so repeated diagnostics or event refreshes do not force avoidable screen renders.

GlassesDevice

MetaGlasses.connect(deviceId) resolves to a GlassesDevice:

await device.startSession();
await device.stopSession();

const capabilities = device.getCapabilities();
const stream = await device.createCameraStream({
  preferredWidth: 1280,
  preferredHeight: 720,
  preferredFps: 30,
});

const display = await device.createDisplaySession();
const media = await device.listMedia();
await device.deleteMedia(media[0].id);

GlassesCameraStream

await stream.startPreview();
await stream.stopPreview();

const snapshot = await stream.captureSnapshot({
  maxWidth: 640,
  format: "jpeg",
});

const photo = await stream.takePhoto();
await stream.startRecording();
const video = await stream.stopRecording();

const unsubscribe = stream.subscribeFrames(
  { fps: 10, maxWidth: 320, format: "rgba" },
  (frame) => {
    console.log(frame.uri, frame.sequence, frame.byteLength);
  },
);

unsubscribe();
await stream.dispose();

Raw frame subscription is opt-in. Keep frame sizes and FPS bounded for app UI workloads.

GlassesDisplaySession

const display = await device.createDisplaySession();

await display.send({
  type: "text",
  title: "Nitro Glasses",
  body: "Display command sent from React Native.",
});

await display.close();

GlassesCameraView

<GlassesCameraView streamId={stream.id} style={{ borderRadius: 12 }} />

The bundled view is a typed preview surface for the active stream. The example app uses it in both mock and native-backed workflows.

Modes

| Mode | Use it for | | ------ | -------------------------------------------------------- | | mock | CI, local demos, docs, and development without hardware. | | real | Native adapter integration through Nitro Modules. | | auto | App-controlled mode selection. |

The current native implementation ships with a deterministic mock backend. The public API is designed so a real Meta Wearables DAT adapter can replace the mock internals without changing app code.

TypeScript

The package exports the public native contract and all data shapes from GlassesNative.nitro.ts, including:

• GlassesConfiguration
• GlassesStatus
• GlassesPermissionState
• GlassesDeviceInfo
• GlassesCapabilities
• GlassesCameraStreamOptions
• GlassesSnapshotOptions
• GlassesFrameSubscriptionOptions
• GlassesMediaAsset
• GlassesDisplayCommand
• GlassesDiagnostics
• GlassesEvent
• GlassesError
• GlassesErrorCode

Use these exported types in app code instead of duplicating string unions or native payload shapes. IDEs can then catch invalid modes, permission names, camera formats, display command types, and lifecycle data before runtime.

Errors

Public helpers throw GlassesError for typed SDK errors where possible.

import { GlassesError } from "react-native-nitro-glasses";

try {
  await device.createCameraStream();
} catch (error) {
  const glassesError = GlassesError.from(error);
  console.log(glassesError.code, glassesError.message);
}

Known error codes include device_not_found, not_connected, session_inactive, stream_not_found, display_session_not_found, unsupported, native_error, and unknown.

Platform Support

| Platform | Status | | -------- | --------------------------------------------------------------------------- | | iOS | Nitro module wiring, permissions, config plugin, and native mock backend. | | Android | Nitro module wiring, permissions, DAT Maven setup, and native mock backend. | | Expo | Development builds with the config plugin. | | Web | Not a primary runtime target. Use React Native runtimes for native modules. |

Troubleshooting

• Expo Go error: build a dev client; Expo Go cannot load Nitro modules.
• Android repository auth fails: provide META_WEARABLES_GITHUB_USER and META_WEARABLES_GITHUB_TOKEN, or set configureAndroidRepository: false.
• No devices in local development: call MetaGlasses.configure({ mode: "mock", mockDeviceCount: 1 }) before reading devices.
• Invalid lifecycle errors: connect first, then start a session, then create camera or display sessions.

Development

bun install
bun run check
bun run release:preflight
bun run example:android
bun run example:ios

Run native example builds before release when changing plugin, native, Nitro, or packaging files.

License

MIT